Email Templates
Create and edit the email templates that workflows and system events send, including subject, body, merge variables, layout, and preview.
Email Templates
Email templates are the reusable content — subject line, HTML body, plain-text body, and merge variables — that your platform sends to learners. Templates are content only: they don't send by themselves. Each one fires either automatically when a system event happens, or when an admin builds a workflow that references it by name. This page covers creating, editing, previewing, and seeding templates from Settings > Email Templates.
How templates send
Every template fires through one of two paths, shown as a tag on each template card:
- Auto-fires — system templates that fire automatically when their event happens (for example, welcome on signup, certificate when issued). The email goes to the one user tied to the event — the new learner, the enrollee, the paying user — and is never broadcast. This tag reflects the eight names the dashboard recognizes as system templates.
- Workflow-only — most templates carrying this tag are inert until an admin builds a workflow that references them by name. Recipients depend on the workflow: a single user for event-driven sends, or an audience filter for scheduled sends.
The Workflow-only tag is not always literal. A couple of templates the dashboard labels this way — notably user.invite and credential.issued — actually auto-fire straight from the backend the moment an invite is sent or a credential is issued, with no workflow wired. Editing those templates changes emails learners already receive, so treat them as live even without a workflow.
The system looks up auto-firing templates by their Template Key (name), not by the trigger event. The Trigger Event field on a template is metadata for discoverability — it does not by itself cause the template to send.
Seed the default templates
If templates are missing, a banner at the top offers to create them. Click Seed default templates (or Seed N default templates) to install the full default set in one call. Seeding is idempotent — templates you have already edited are preserved, never overwritten — so it is safe to run even when most templates already exist.
When a system template is missing, the corresponding system email is silently dropped — no error, no send. If the missing-templates banner appears, seed the defaults so welcome, enrollment, certificate, and payment emails go out.
Create a template
- Click Create Template.
- Enter a Template Key (name) — unique per tenant. System templates use dotted names like
user.welcome. This key cannot be changed after creation. - Enter a Display Name (for example, Welcome Email) and a Subject.
- Choose a Category: Transactional, Marketing, or Custom.
- Optionally pick a Trigger Event from the grouped, searchable list to record when the template is meant to fire.
- Fill in HTML Content and, optionally, Plain Text Content.
- Click OK to save. Template key, display name, and subject are required.
Edit a template
Select any template from the list to open it in the editor. Each field:
| Field | Purpose |
|---|---|
| Display Name | Friendly label shown in the dashboard. |
| Template Key (name) | System lookup key. Editable only when creating. |
| Subject | The email subject; supports merge variables. |
| HTML Content | The rich body sent to recipients. |
| Plain Text Content | Fallback body for text-only clients. |
| Category | Transactional, Marketing, or Custom. |
| Trigger Event | Metadata marking when the template is intended to fire. |
| Template is active | Uncheck to keep a template on file without sending. |
Click Save to persist changes. Use the delete button (with confirmation) to remove a template.
What Category controls at send time
Category is more than a list filter — it changes how the message is sent. When a template is tagged Marketing, every send attaches RFC 8058 one-click unsubscribe headers (List-Unsubscribe and List-Unsubscribe-Post: One-Click) carrying a per-recipient signed unsubscribe link. Those headers are one of Gmail's and Yahoo's strongest "bulk mailing" signals, so a Marketing message typically lands in the recipient's Promotions tab. Transactional and Custom templates get no unsubscribe header and stay in the Primary inbox.
Pick the Category that matches the mail's real purpose. Tagging an important one-to-one announcement as Marketing can send it to the Promotions tab (lower open rate); tagging a true newsletter or bulk digest as Transactional omits the one-click unsubscribe that recipients — and bulk-sender rules — expect. This is a send-time behavior change, not just a label.
Merge variables
Subject and body accept merge fields written as {{ variable }} — for example {{ user.first_name }} or {{ tenant.name }}. The editor lists the variables available for the selected template beneath the Subject field. Different templates expose different variables: a certificate email offers certificate.certificate_url and certificate.expiry_date, while a payment email offers payment.amount and payment.currency. Only use the variables listed for that template — unrecognized variables won't resolve.
Plain text auto-sync
Plain-text content is auto-generated from your HTML as you type. Once you edit the plain-text field directly, it stops updating automatically and shows Customised. Won't auto-update from HTML. Click Reset to auto-generated to discard your custom version and re-enable syncing.
Layout and branding
The Layout controls decide how the body is wrapped at send time:
- Wrap in tenant theme — when on, your body is wrapped with the logo, brand colors, font, and social footer pulled from your active theme. Turn it off only if you have authored the complete HTML yourself (legal notices, co-branded partner sends).
- Layout variant — choose one of three when wrapping is on:
- Minimal — no logo, terse card. Best for OTPs and password resets.
- Branded — logo header plus social footer. The default transactional look.
- Marketing — branded, with a hero image and larger call to action. Best for digests and newsletters.
Preview
Click Preview to open the preview modal. The preview is rendered server-side using your live edit state, so unsaved changes appear and the full layout wrapping (logo, brand colors, social footer) is applied exactly as recipients would see it. Sample values are substituted for each merge variable so the email reads with realistic data. Toggle between HTML and Plain Text, and click Refresh to re-render after further edits.
Preview always applies your active theme's branding when Wrap in tenant theme is on. If the logo or colors look wrong, update your theme rather than editing the template body.
Filtering
Use the search box to find a template by name, and the category dropdown to filter by Transactional, Marketing, or Custom. Inactive templates are tagged in the list so you can spot ones that won't send.
