Email Templates — Reference
The Email Templates surface is the transactional-email plane for every SGEN site. It owns the catalogue of templates the platform uses to compose automated messages — order confirmations, welcome emails, password-reset prompts, receipts, form notifications, and the rest — the variable substitution that fills runtime values into each message at send time, and the brand customization that applies the site's header, footer, and styling on top of every outbound email.
This page is a reference for platform engineers and integrators who need to understand the surface before extending it, scripting against it, or scoping an email-template integration. Customer-facing setup walkthroughs live in the customer docs set; this page describes the shape of the surface, not the steps to drive it.
Overview
Email Templates live under the Settings → Email → Templates module in SG-Admin. The module renders four primary views — the template list, the per-template editor (with a live preview), the variable reference panel, and the brand-customization editor — and exposes write operations for template edit, brand customization edit, test send, and template restore-to-default.
The module is paired by convention with every surface that emits transactional email — Orders (order confirmations, shipment notifications, refund receipts), Users (welcome, password reset, account changes), Forms (submission acknowledgements, recipient notifications), Subscriptions (renewal notices, payment failures), and Events (registration confirmations, reminders). Engineers reading the SG-Admin source will see the read half (template enumeration, variable schema lookup, preview rendering) split from the write half (template edits, brand customization, test sends); the reference below describes the combined surface as it appears to a calling integration.
A second surface — send log — lives adjacent under the same module. The send log records every transactional email the platform has emitted, with recipient, template ID, send timestamp, delivery status, and bounce or complaint feedback when available.
Where it lives in SG-Admin:
- Sidebar: SG-Admin → Settings → Email → Templates
- URL prefix:
/sg-admin/email_templates/ - View templates:
application/views/Admin/EmailTemplates/
┌──────────────────────────────────────────────────────────────────────┐│ SG-Admin → Settings → Email → Templates │├──────────────────────────────────────────────────────────────────────┤│ Template Surface Status Last edited ││ ──────────────────────── ───────────── ────────── ─────────────││ Order confirmation Ecommerce Customised 3 days ago ││ Shipment notification Ecommerce Default — ││ Refund receipt Ecommerce Customised 3 days ago ││ Welcome — new account Users Default — ││ Password reset Users Customised 8 days ago ││ Form submission receipt Forms Default — ││ Subscription renewal Subscriptions Default — ││ Event registration Events Customised 1 day ago ││ ││ [⋯ Edit] [⋯ Test send] [⋯ Restore default] │└──────────────────────────────────────────────────────────────────────┘Actions
The Email Templates surface exposes the following operations. Each is described by what it does to the data, not by its internal method name.
List templates
Returns the templates configured for the current site, grouped by the originating surface. Each row carries the template name, the surface that triggers it, the customization status (default if the operator has not edited the shipped content, customised if the operator has saved an edit), and the last-edited timestamp. The list is non-paginated — the template count is fixed by the platform's emitting surfaces.
Edit template
Opens the per-template editor. The editor exposes the subject line, the preview text (the snippet shown in the recipient's inbox list), the body content (rich text or block-based, depending on the template), and a variable reference sidebar that lists every substitution available to the template. The live preview renders against a sample data set drawn from the recipient's real account where available, or against a built-in fixture otherwise. Submit replaces the stored template definition.
Test send
Sends a one-off message using the current draft (whether saved or unsaved) to a chosen recipient. Required input: the destination email address. The send uses the same delivery pipeline as a real transactional send, including DKIM signing and the site's configured sender domain. Test-send events are recorded in the send log with a test flag.
Restore default
Reverts a customised template to the platform's shipped default. The surface prompts for confirmation, lists the diff between the customised version and the default (for audit), and on confirm replaces the stored content with the default and clears the last_edited_at field. The operator's prior customisation is retained in a version history for one retention period.
Edit brand customization
Opens the brand-wrap editor. The brand wrap is a global header-footer-style block applied on top of every template body before send. Captures the logo image, header background colour, body text colour, link colour, footer block content (typically the site address, contact link, and unsubscribe link for transactional context), and an optional sender-name override. Submit replaces the stored brand definition; subsequent sends across all templates render with the new wrap.
View variable schema
For a chosen template, returns the catalogue of variables the substitution engine will resolve at send time. Each entry carries the variable name (for example, {{order_number}}), the runtime type (string, currency, date, URL, array), and an example value. Templates may safely include any variable in the schema; references to variables outside the schema render as a literal placeholder so the operator can identify the typo in the live preview.
Preview against record
For a chosen template and a chosen target record (an order ID, a user ID, a form submission ID — whichever applies to the template's surface), renders the template substituted against that record. Used by the editor's live preview and by the test-send to inspect a real customer's message before delivery.
View send log
A read path that returns the platform's transactional-email send history. Filterable by template, recipient, surface, date range, and delivery status (sent, delivered, bounced, complained, deferred). The send log is read-only from the operator's side; events are written by the delivery pipeline.
Data model
A template record carries the following fields. Field names below are the conceptual shape — the on-disk column names match closely but are not contractually stable across releases.
| Field | Type | Notes |
|---|---|---|
id | integer | Primary key. Stable across edits. |
slug | string | Identifier used by the emitting surface — for example, order-confirmation. Unique. |
surface | string | The originating surface — ecommerce, users, forms, subscriptions, events. |
subject | string | Template-substituted subject line. |
preview_text | string | Template-substituted inbox preview snippet. |
body | text | Template body. Rich-text or block-based depending on the template. |
is_customised | boolean | False when the body matches the shipped default. |
default_body | text | Read-only. The platform's shipped default content, used by restore. |
last_edited_at | timestamp | Set on every edit. Null on default templates. |
last_edited_by | integer | Operator ID. Null on default templates. |
created_at | timestamp | Set on first edit, immutable. |
updated_at | timestamp | Touched on any edit. |
| Field | Type | Notes |
|---|---|---|
id | integer | Primary key. One per site. |
logo_url | string | Reference to the Media library. |
header_bg_colour | string | Hex value. |
body_text_colour | string | Hex value. |
link_colour | string | Hex value. |
footer_content | text | Rich text — typically site address, contact link, unsubscribe block. |
sender_name | string | Optional. Overrides the default sender name on outbound messages. |
updated_at | timestamp | Touched on any edit. |
| Field | Type | Notes |
|---|---|---|
id | integer | Primary key. |
template_id | integer | Foreign key to the template. |
recipient_email | string | The destination address. |
recipient_id | integer | Optional. Foreign key to a user or customer record when available. |
sent_at | timestamp | When the delivery pipeline emitted the message. |
delivery_status | enum | sent, delivered, bounced, complained, deferred. |
feedback | text | Structured feedback from the receiving mail server, if any. |
is_test | boolean | True for test-send events. |
TEMPLATE BRAND CUSTOMIZATION├── id integer ├── id integer (one per site)├── slug string (unique) ├── logo_url string├── surface string ├── header_bg_colour hex├── subject string ├── body_text_colour hex├── preview_text string ├── link_colour hex├── body text ├── footer_content text├── is_customised boolean └── sender_name string (optional)├── default_body text (read-only)└── last_edited_at timestamp↓ resolved at send timeVARIABLE SCHEMA (per template)├── variable name string (e.g. {{order_number}})├── runtime type string | currency | date | URL | array└── example value from real record or fixture↓ each send emitsSEND LOG ENTRY├── recipient_email string├── recipient_id integer (optional)├── sent_at timestamp├── delivery_status sent | delivered | bounced | complained | deferred└── is_test booleanVariable substitution. At send time the delivery pipeline resolves every {{variable}} reference in the subject, preview text, and body against the schema declared for the template's surface. Unknown references render as the literal placeholder (visible in the message) so the operator can identify the typo. Currency and date variables format according to the site's configured currency and locale.
Brand wrap composition. Before a template body is queued for delivery, the brand wrap is rendered around it — header above, footer below — with the brand record's colours applied to the wrap stylesheet. The wrap is composed at send time, not at edit time; brand changes apply retroactively to every subsequent send, including templates that were not edited.
Default-vs-customised state. A template is is_customised = false until the operator saves an edit. While in the default state, the platform may ship updates to the default body in product releases and the live template reflects the new default. After an edit, the template is is_customised = true and is no longer updated by platform releases — restore brings the operator back to the current default.
Permissions
Access to the Email Templates surface is gated at two layers.
Layer 1 — admin gate. Every action under SG-Admin passes through the platform's standard admin access check at request entry. An unauthenticated request never reaches the Email Templates surface.
Layer 2 — per-action capability. Within SG-Admin, each Email Templates action checks a capability associated with the calling operator's role. The default role configuration ships with three roles — Administrator, Editor, Viewer — and the capability map is:
| Capability | Administrator | Editor | Viewer |
|---|---|---|---|
| List templates | ✔ | ✔ | ✔ |
| Edit template | ✔ | ✔ | — |
| Test send | ✔ | ✔ | — |
| Restore default | ✔ | — | — |
| Edit brand customization | ✔ | — | — |
| View variable schema | ✔ | ✔ | ✔ |
| Preview against record | ✔ | ✔ | — |
| View send log | ✔ | ✔ | — |
Recipient-scope check on preview-against-record. Rendering a real record into the preview reveals personal data — the buyer's name, address, order line items. The preview action runs against the same access rules that the originating surface enforces: an operator who cannot view a specific order cannot preview an order-confirmation template substituted against that order.
Audit. Every write — template edit, brand customization edit, restore default, test send — emits an Activity Log entry. The log records the acting operator, the target template (or brand record), and the change shape. Test sends are tagged distinctly from real sends so a compliance audit can filter them out. Send-log entries are not audit-log entries; the send log is operational, the audit log is governance. Activity Log retention is governed by the site's general settings.
EMITTING SURFACE(Orders, Users, Forms, Subscriptions, Events)│▼"Send template <slug> to <recipient>against record <id>"│▼┌─────────────────────────────────┐│ Variable substitution │ unknowns render as literal│ (subject + preview + body) │└──────────────┬──────────────────┘▼┌─────────────────────────────────┐│ Brand wrap composition │ header + footer + colours│ (applied at send, not edit) │ applied around body└──────────────┬──────────────────┘▼┌─────────────────────────────────┐│ Delivery pipeline │ DKIM sign, sender domain,│ │ send via configured SMTP└──────────────┬──────────────────┘▼Send log entry(sent | delivered | bounced | complained | deferred)│▼Activity Log entry (writes only)Related references
- Orders — Reference. Emits order-confirmation, shipment-notification, and refund-receipt templates against order records.
- Users — Reference. Emits welcome, password-reset, and account-change templates against user records.
- Forms — Reference. Emits submission-acknowledgement (to the submitter) and submission-notification (to the configured recipient) templates against form submission records.
- Subscriptions — Reference. Emits renewal-notice, payment-failure, and cancellation-confirmation templates against subscription records.
- Events — Reference. Emits registration-confirmation and event-reminder templates against event-registration records.
- Settings — Email — Delivery. Owns the SMTP credentials, the sender domain, DKIM signing keys, and the bounce-handling configuration that the delivery pipeline reads.
- Media — Reference. The brand logo and any inline images embedded in template bodies are stored in the Media library and referenced by URL.
- Activity Log — Reference. Template edits, brand-customization edits, restore-default events, and test sends surface as audit-log entries.
/docs/email-templates.