Email Marketing
> **Prerequisite:** Your outgoing mail server must be configured by an administrator (Settings → Technical → Email → Outgoing Mail Servers) and your domain must be SPF/DKIM-verified. Without this, mailings will sit in *Queue* or bounce en masse.
## 1. What the module does
The Email Marketing app lets you:
- Build HTML emails using a drag-and-drop block editor.
- Send them to a curated audience — a **Mailing List**, a filtered view of another model (Patients, Contacts, Sale Orders…), or an imported CSV.
- Track **delivery, opens, clicks, replies, bounces, and unsubscribes** in real time.
- Run **A/B tests** on subject line, sender, or content and auto-pick the winner.
- Group related mailings under **Campaigns** for reporting.
- Manage **blacklists** so unsubscribed or invalid addresses are never sent to again.
## 2. Top-level menus
When you open **Email Marketing**, the menu bar looks like this:
| Menu | What lives here |
|---|---|
| **Mailings** | The email campaigns you create and send. |
| **Mailing Lists** | Reusable audience lists and the contacts in them. |
| **Campaigns** | Optional grouping of mailings for reporting (visible with developer mode or when Marketing Campaigns is enabled). |
| **Reporting** | Open/click/bounce analytics across mailings, plus the Link Tracker. |
| **Configuration** | Settings, blacklist management, UTM tags, link trackers. |
## 3. Mailings
### Mailings → Mailings
This is the main list of every email you've drafted or sent. Each row shows the subject, recipient target (model + audience), status, and headline KPIs (sent / delivered / opened / clicked / replied / bounced).
**Creating a mailing (step by step):**
1. Click **New**.
2. **Subject** — the email subject line. Keep under ~60 characters so it isn't clipped in inboxes.
3. **Recipients** — pick the model the audience lives on:
- *Mailing List* — send to one or more saved lists (most common for newsletters).
- *Contact*, *Lead/Opportunity*, *Sales Order*, *Event Registration*, etc. — send to records in that model, optionally narrowed by a filter (e.g. "Customers with a follow-up in 30 days").
4. **Sender name and email** — your *From*. Use an address on your verified domain.
5. **Reply-To** — where replies land. Defaults to the sender.
6. **Mail Body** — build the email itself:
- Pick a **Template** (Newsletter, Promotions, Event, Plain Text, Start from Scratch).
- Drag blocks (Hero image, Text + Image, Button, Footer) onto the canvas and edit inline.
- Use **Dynamic Placeholders** to insert recipient fields (e.g. the recipient's first name).
7. **Settings tab** — pick a Campaign, UTM source/medium, and advanced options like "send on behalf of" and reply tracking.
8. **Send** (or **Schedule**, **Test**, **Save as Template**).
**Status lifecycle:**
- *Draft* — still being edited.
- *In Queue* — sent button pressed; mails are being generated/queued.
- *Sending* — the queue is being drained by the mail server.
- *Sent* — all emails dispatched.
- *A/B Test* — an A/B variation (see section 4).
**Key buttons on a sent mailing:**
- **Test** — send the current mailing to an arbitrary email (yourself) before the real blast.
- **Send** — schedule for immediate delivery.
- **Schedule** — queue for a specific date/time.
- **Retry** — resend only the failed recipients.
- **Cancel** — stop a queued (not yet sent) mailing.
**The KPI strip** on a sent mailing shows Sent, Delivered, Opened, Replied, Clicked, Bounced, Unsubscribed, and Invalid counts — each is clickable to open the list of recipients behind that number.
### Mailings → A/B Tests
Visible once you enable A/B testing on a mailing (**A/B Tests** tab → *Allow A/B Testing*). You can create alternative versions of the same mailing (different subject, sender, or body), define what percentage of the audience gets each variant, pick the winning metric (highest open rate, click rate, reply rate, etc.), and let auto-send the winner to the remaining audience after the test window.
**Typical workflow:**
1. Create mailing A with your primary subject.
2. Toggle **A/B Testing**. Set *Percentage* (e.g. 20%) and *Winner Selection* (e.g. *Highest Click Rate*).
3. From the mailing, click **Create an Alternative Version**. Change the subject line or body.
4. Schedule both. After the test period, sends the winner to the remaining 80%.
## 4. Mailing Lists
### Mailing Lists → Mailing Lists
Reusable audiences (e.g. "Newsletter Subscribers", "VIP Patients", "Lapsed Customers"). Each list tracks:
- **Total contacts** in the list.
- **Opt-outs** (people who unsubscribed from this list).
- **Public** flag — when on, the list is selectable on the website subscription form.
**Common actions on a list:**
- **Add contacts** — directly, or import via CSV from the list header.
- **Merge into another list** — the *Action* menu lets you merge a list's contacts into another.
- **View mailings sent to this list**.
### Mailing Lists → Mailing Contacts
The global contact database for the Email Marketing app (model `mailing.contact`). Each contact has:
- Email, name, company, country, tags.
- **Subscription** sub-records — one row per list the contact is on, each with an opt-out flag.
- **Blacklist** flag — set when the address has been globally blacklisted.
**Tips:**
- Use **tags** to slice your contact database without creating a new list for every segment.
- Importing contacts via the *Import* button on this view is the easiest way to seed a new list — just include a *Mailing Lists* column with the list names.
### Mailing Lists → Blacklisted Email Addresses
Global blacklist (model `mail.blacklist`). An address on this list is never emailed by *any* mass mailing, regardless of which list it's on. Addresses land here when:
- A recipient clicks the **Unsubscribe → Blacklist Me** link in a mailing.
- An admin adds them manually.
- The system auto-blacklists after repeated hard bounces (if the setting is enabled).
**Manage the blacklist:**
- Click a row to see the reason and the date it was blacklisted.
- Use **Unblacklist** if the address was added by mistake and the person has reconfirmed opt-in.
## 5. Campaigns
**Campaigns** are optional containers that group related mailings (and other marketing activities) for reporting — e.g. a "Spring Recall Campaign" might include a reminder email, an SMS, and a follow-up email. In you'll see this menu automatically when the Marketing Campaigns feature is enabled or developer mode is on.
**Use a campaign when:**
- You want aggregate metrics (total opens, clicks, conversions) across multiple sends.
- You want to compare one campaign against another in Reporting.
- You're using Marketing Automation flows and need a container for the emails they send.
## 6. Reporting
### Reporting → Mailings (list with analytics)
The same list as Mailings → Mailings, but surfaces the analytics columns front-and-centre. Sort by Click Rate or Reply Rate to see which mailings performed best.
### Reporting → Link Tracker
Every clickable link in a mailing is rewritten through link tracker so opens and clicks can be attributed back. The Link Tracker page lists every tracked URL, with:
- **Click counts** by mailing.
- **UTM source / medium / campaign** captured from the mailing's settings.
- A **short URL** you can reuse in other channels (SMS, social).
**Reading the Link Tracker:**
- Group by **Campaign** or **Source** to see which channel drives the most clicks.
- Click a URL row to see every click event (date, country, user agent if captured).
### Reporting → Traces
A **trace** is a single message's journey for one recipient. Traces let you debug delivery issues at the recipient level — you can filter by *Bounced*, *Opened*, *Replied*, *Clicked*, or *Cancelled*, and see the exact error for bounces (e.g. "mailbox full", "domain does not exist").
## 7. Configuration
### Configuration → Settings
Module-level preferences (usually set once and forgotten):
- **Mailing Campaigns** — enable the Campaigns menu.
- **A/B Testing** — enable A/B tests.
- **Blacklist Option When Unsubscribing** — show a "blacklist me" button alongside the list-unsubscribe.
- **Dedicated Email Server** — route mass mailings through a separate outgoing mail server so transactional mail isn't blocked when you send a large blast.
- **Mailing Domain** — the domain used for tracking links and the unsubscribe page (must match your SPF/DKIM setup).
### Configuration → Blacklisted Email Addresses
Same list as under Mailing Lists → Blacklisted; duplicates it here for convenience.
### Configuration → UTM (Link Tracker) → Campaigns / Sources / Mediums
The UTM master lists behind the tracker — *Source* = where (newsletter, social), *Medium* = how (email, web, SMS), *Campaign* = which promotion. Pre-populate these so your team picks consistent values on each mailing, which makes Reporting meaningful.
## 8. Typical end-to-end workflows
### A. Monthly newsletter to an existing list
1. *Mailing Lists → Mailing Lists* — confirm the audience is up to date.
2. *Mailings → New* — pick the list, build the email with the Newsletter template.
3. Add a UTM *Source = newsletter*, *Medium = email*, *Campaign = 2026-04 newsletter*.
4. **Test** to yourself. Check phone and desktop rendering.
5. **Schedule** for Tuesday 10am (typically higher open rates than Monday morning).
6. Over the next 48 hours, watch the KPI strip and Link Tracker.
### B. Targeted re-engagement to lapsed customers
1. *Mailings → New* — set Recipients to *Contact* (or *Patient*) with a filter like "Last Order Date < 6 months ago".
2. Use a soft subject line, a short body, and one clear call to action.
3. Enable **A/B Testing** with two subject lines at 20% each; let the winner auto-send to the remaining 60%.
4. Review in Reporting → Traces after 7 days; blacklist hard-bounced addresses.
### C. Importing a purchased list
1. *Mailing Lists → Mailing Contacts → Import*.
2. Map columns. Include *Mailing Lists* to auto-enrol contacts.
3. Before the first send, **validate** — your sender reputation is at stake. Ideally seed a small batch first and watch bounce rate.
## 9. Tips and common gotchas
- **Always send a Test first.** Image paths, dynamic placeholders, and links break in surprising ways; catching it before the blast is cheap.
- **Warm up new sending domains.** A brand-new *From* domain with no history should start with small audiences and scale up over days — large blasts from cold domains get silently filtered.
- **Respect the Blacklist.** Re-adding a blacklisted address because "it was a mistake" should require documented opt-in. The blacklist exists to protect your sender reputation.
- **Unsubscribe link is mandatory.** Every mass email automatically includes an unsubscribe link; do not remove or hide it. Hiding it risks CAN-SPAM / CASL / GDPR violations.
- **High bounce rates hurt deliverability.** If a mailing bounces >5% of addresses, pause and clean the list before sending more. Re-use Reporting → Traces with the *Bounced* filter to identify them.
- **Dynamic placeholders have defaults.** Always provide a default (e.g. `{{ object.name or 'there' }}`) so the email doesn't render "Hi ," for contacts missing a name.
- **Schedule into the recipient's time zone.** sends in the server time zone; if your audience is spread across regions, segment the mailing per region and schedule accordingly.
- **Review the Link Tracker before sending.** If links aren't being rewritten, tracking won't work — verify the Mailing Domain in Configuration → Settings is correct.
- **A/B only one variable at a time.** Testing both subject *and* body at once means you can't know which change drove the result.
- **Archive old mailings, don't delete.** Sent mailings carry the analytics history; deleting them loses the metrics and makes year-over-year comparisons impossible.
## 10. Quick reference — what clicks where
| I want to… | Menu path |
|---|---|
| Draft or send a new campaign | Mailings → Mailings → New |
| Send a test to myself | Open mailing → Test |
| Build a reusable audience | Mailing Lists → Mailing Lists → New |
| Import a CSV of contacts | Mailing Lists → Mailing Contacts → Import |
| See who clicked a link | Reporting → Link Tracker |
| Find out why an address bounced | Reporting → Traces → filter *Bounced* |
| Unsubscribe / blacklist an address | Configuration → Blacklisted Email Addresses |
| Tag mailings for later reporting | Mailing → Settings → Campaign (and UTM Source / Medium) |
| Enable A/B testing globally | Configuration → Settings → A/B Testing |