Email Layouts
Database-managed email chrome — the branded wrapper around every system email, its slot dialect, editor, and version history.
Overview
An email layout is the chrome wrapped around rendered email content: the document shell, styles, header, body slot, and footer. Layouts live in the database (email_layouts), so the branded wrapper is editable from the admin panel instead of being a fixed Blade view.
The shipped Signals layout is seeded as a system layout and marked as the default, so a fresh install uses it for system emails. It is light by default: a pale page, a white card with a 1px frame, a white header with your logo (or your company name in the framed wordmark, in your primary colour), a thin rule in your primary colour, quiet sentence-case type, a square button and links in your accent colour, and a pale footer tinted with your primary colour carrying the reason for the email, unsubscribe or notification-preference links where they apply, and your company name and default warehouse address. Where the reader's mail app is in dark mode, the same email switches to a dark card with your primary colour as a solid header band.
Where it lives
Routes:
- List:
/admin/settings/email-layouts(admin.settings.email-layouts) - Edit:
/admin/settings/email-layouts/{layout}/edit(admin.settings.email-layouts.edit)
Open Admin → Preferences → Email Layouts. Both pages require email-templates.manage, on mount and on every action.
Key workflows
| Action | Behaviour |
|---|---|
| New Layout | Creates a layout seeded with the master markup; the key is slugified from the name and suffixed until unique |
| Duplicate | Same, but pre-filled with the source layout's HTML and named Copy of … |
| Edit | CodeMirror editor with live preview, slot/field browser, and version history |
| Colour scheme | Tenant-wide, on the edit page: Match reader (default — light, dark where the reader's mail app is in dark mode), Always light, or Always dark (dark card and brand band header in every client). Stored as the email_layout.header_style setting, outside the layout HTML, so it survives Reset to Default and upgrades |
| Reset to Default | System layouts only, shown when the body differs from the shipped markup: replaces the body with the current shipped design. The customised body is saved as a version first |
| Make Default | Promotes one layout to the single default in a transaction, clearing the flag on every other row |
| Active toggle | Deactivates a layout so it can no longer be picked; the default layout cannot be deactivated |
| Delete | Removes a layout — system and default layouts are protected |
The first layout created on an install with no default becomes the default automatically.
Resolution order
The email renderer picks a layout in this order:
- the layout chosen on the email template (
email_templates.email_layout_id), when it is still active; - the active default layout;
- a hard fallback to the shipped master markup,
EmailLayoutSeeder::masterBodyHtml(), rendered without touching the database.
Transactional mail must never fail because a layout was edited, deactivated, or deleted, so every database path is wrapped: a missing table, a query failure, or a render error logs a warning and degrades to the shipped markup.
Every HTML email also gets a plain-text alternative at send time (generated automatically), derived from the final HTML: headings and paragraphs on their own lines, list items with a dash, links followed by their URL, the logo as its alt text, and the hidden preheader left out. A message that already carries a text part is left alone.
The default layout is cached under email-layouts:default for one hour and the cache is dropped by every layout write (create, update, delete, set-default) and by the seeder.
Layout dialect
A layout body is plain HTML plus three placeholder forms. Styles are inlined onto each element after rendering, so <style> rules survive email clients.
Raw slots — {{{ slot }}}
Inserted unescaped, because they carry rendered HTML:
| Slot | Contents |
|---|---|
{{{ body }}} |
Required — the rendered email template content |
{{{ eyebrow }}} |
Short label above the heading |
{{{ preheader }}} |
Hidden inbox preview text |
{{{ footer_context }}} |
Contextual footer line |
{{{ unsubscribe_url }}} |
Unsubscribe link for customer communications |
{{{ preferences_url }}} |
Link to the recipient's notification preferences, set on staff notifications |
An unwrapped slot with no value renders as an empty string.
Conditional blocks — {{{ if name }}} … {{{ else }}} … {{{ endif }}}
The name is a slot or a dotted branding field. The block is kept only when the value is not empty; the optional else branch is used otherwise. Blocks do not nest. This keeps optional chrome from leaving empty padded elements behind:
{{{ if company.logo_url }}}
<img src="{{ company.logo_url }}" width="{{ company.logo_width }}" height="{{ company.logo_height }}" alt="{{ company.name }}">
{{{ else }}}
<span>{{ company.name }}</span>
{{{ endif }}}
Merge fields — {{ field.path }}
Escaped values resolved from the branding data set by MergeFieldRenderer — the same engine, grammar, and filter catalogue as communication and email templates:
{{ field.path | filter:arg | filter2 }}
Malformed {{ … }} blocks are left as literal text. Unknown fields render blank unless a default filter is chained. Values are escaped (HTML and markdown metacharacters) after filters run. Filter chains run left to right; core filters include upper, lower, title, default, truncate, plural, date, time, currency, and number. See Merge Field Filter Registry.
| Field | Value |
|---|---|
{{ company.name }} |
company.name setting, falling back to the application name |
{{ company.logo_url }} |
Signed URL of a PNG copy of the uploaded logo (Outlook for Windows cannot show WebP); blank when there is no usable logo |
{{ company.logo_width }} / {{ company.logo_height }} |
Logo display size in pixels, at most 200 × 48 |
{{ company.address }} |
The default warehouse's postal address on one line, or blank |
{{ brand.primary }} / {{ brand.accent }} |
Raw branding colours (#rrggbb), for fills |
{{ brand.primary_ink }} / {{ brand.accent_ink }} |
Text-safe versions that meet WCAG AA on the white card |
{{ brand.primary_ink_dark }} / {{ brand.accent_ink_dark }} |
Text-safe versions for the dark-mode card |
{{ brand.on_primary }} |
Text colour to place on the primary fill |
{{ brand.button }} / {{ brand.on_button }} |
Button fill and label colour (the accent, adjusted only when it cannot stand out or carry AA text) |
{{ brand.button_dark }} / {{ brand.on_button_dark }} |
The same pair for dark mode |
{{ theme.* }} |
Every colour of the chosen scheme (page, card, frame, text, heading, link, eyebrow, button, on_button, footer_bg, footer_text, …): the light scheme, or the dark one for Always dark |
{{ dark.* }} |
The same keys for the dark scheme, for prefers-color-scheme rules |
{{ header.background }} / {{ header.ink }} / {{ header.plate_padding }} |
Header colours and logo plate padding for the chosen scheme |
{{ header.match }} / {{ header.light }} / {{ header.dark }} |
Non-empty for the chosen scheme, for {{{ if header.match }}} blocks |
{{ header.color_scheme }} |
Value for the color-scheme meta tag |
{{ brand.primary_tint }} |
Pale tint of the primary colour (the light footer) |
{{ labels.unsubscribe }} / {{ labels.preferences }} |
Translated footer link text |
{{ locale }} |
Current locale, for <html lang> |
{{ current_year }} |
Current year, for the footer |
{{ eyebrow }} / {{ preheader }} / {{ footer_context }} |
Escaped forms of the same values (already-escaped text is escaped once, not twice) |
{{ unsubscribe_url }} / {{ preferences_url }} |
The link URLs |
Colour fields keep their #, so they can be used inside a <style> block as well as in inline styles.
Conditionals stay layout-specific ({{{ if slot }}} above). MergeFieldRenderer does not parse them; only {{ field }} substitution is shared with templates.
Editor
The edit page splits into a browser column and an editor/preview pair:
- Slots and Branding Fields panels insert a snippet at the cursor; when CodeMirror is unavailable the page falls back to a plain textarea and inserts server-side.
- Layout HTML — CodeMirror 6 source editor.
- Live Preview — the current buffer rendered with sample body copy, eyebrow, preheader, footer context, and unsubscribe URL in a sandboxed iframe. A dialect error is reported in the preview pane rather than thrown.
- Versions — every save first snapshots the preceding body into
email_layout_versions(append-only, numbered, attributed to the saving user). Restore loads a prior body back into the editor and saves it, which itself snapshots the current one. - Make Default and the Active checkbox apply the same guards as the list page.
Choosing a layout per template
The email template form carries an Email Layout picker. The first option — Default — {layout name} — leaves email_layout_id null so the template follows whichever layout is currently the default; that default layout is listed only there, not again as a separate row. Other active layouts remain selectable. The template preview renders through the selected layout. See Email Templates.
Seeding
EmailLayoutSeeder creates the master Signals layout (is_system, default when no default exists yet) and is idempotent — re-running refreshes the name, description, and system flag without overwriting an edited body. It runs from CompleteSetup and is listed on the Database Seeders panel.
How a new default design reaches existing installs
A customised layout is never overwritten. When the shipped markup changes:
- an install whose master layout body is still byte-for-byte an preceding shipped markup is moved to the new design by a migration (and by the seeder). The prior body is saved as a layout version first, so it can be restored from Versions;
- an install whose master layout was edited keeps its own markup. An admin can opt in with Reset to Default on the layout's edit page; the edited body is saved as a version first.
Released shipped markups are recognised by their SHA-256 fingerprints in EmailLayoutSeeder::SHIPPED_MASTER_BODY_HASHES. When changing masterBodyHtml(), add the fingerprint of the markup being replaced and ship a migration that calls EmailLayoutSeeder::refreshUnmodifiedMaster().
Client support
The shipped layout is table-based with role="presentation" tables, a 600px fluid container (an Outlook-only wrapper fixes the width where max-width is ignored), styles inlined at send time, and a hidden preheader. Headings and body use Helvetica; the wordmark uses the Chakra Petch web font where the client loads it. Outlook for Windows is given Segoe UI instead so it never falls back to Times New Roman. Buttons are drawn with borders rather than padding so Outlook's Word engine keeps their shape. With Match reader, dark mode uses prefers-color-scheme (Apple Mail, iOS Mail, Outlook for Mac, some Android clients) and Outlook.com's dark-mode hooks; everyone else, including Gmail and Outlook for Windows, sees the light design. On the brand band the logo sits on a white plate so logos drawn for light backgrounds stay visible. Gmail's apps darken light emails themselves; the logo cell keeps a white background-image there so a dark logo stays legible. Always dark paints the dark scheme inline, so it holds in every client.