Skip to content

armgit / spree

Public Imported from GitHub
0

Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.

Documented editing customer email templates and branding

Damian Legawiecaf2adb6abb89
diff --git a/CLAUDE.md b/CLAUDE.md
index 2e03f9bc25..8befb54729 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -435,6 +435,8 @@ Every email renders from a Liquid template written in MJML, never ERB. See `docs
- **In templates**: output is HTML-escaped automatically (`| raw` only for HTML sanitized on write). Filters: `money`, `money_with_currency`, `date` (store time zone), `t` (Spree translation keys, so one template serves every language). An unknown variable raises in development and test.
- **When you add or change an email**: if customers receive it, update `docs/developer/customization/email-variables.mdx` by hand with its variables, add it to `spree/emails/spec/mailers/spree/rendered_emails_spec.rb`, and give it a mailer preview (shown at `/rails/mailers` in development) in `spree/emails/lib/spree/emails/previews/` or, for staff emails, `spree/core/lib/spree/core/previews/`.
- **Don't** add ERB email views, mailer view helpers, or model calls from templates. Apps' own mailers that call `mail` with ERB views still work: `layouts/spree/base_mailer.html.erb` wraps them in the Liquid layout.
+- **Merchants edit customer emails in the dashboard** (`docs/plans/6.0-email-template-editor.md`). A store's published version is found before the file, per language. A new **customer** email must be registered in `Spree.editable_email_templates` (in `spree/emails/lib/spree/emails/engine.rb`) with a sample builder in `spree/emails/app/services/spree/emails/samples/`, and added to the dashboard's variables manifest; never register staff, store-owner or seller emails. Changing a default template shows merchants who customized it an "updated by Spree" notice, so change defaults deliberately.
+- **Colors and fonts come from `store.branding`**, never hard-coded in a customer template. Generate types with `cd spree/api && bundle exec rake typelizer:generate`, which runs inside `spree_emails` so the API and email serializers both load.
### API Authentication
diff --git a/docs/developer/customization/email-variables.mdx b/docs/developer/customization/email-variables.mdx
index af873c4f4d..4ad4931a87 100644
--- a/docs/developer/customization/email-variables.mdx
+++ b/docs/developer/customization/email-variables.mdx
@@ -42,7 +42,8 @@ Each object's fields, and the fields of the objects nested in it.
### `store`
-- `store`: `id`, `name`, `address`, `mail_from_address`, `default_currency`, `default_locale`, `url`, `support_email`, `logo_url`, `logo_width`
+- `store`: `id`, `name`, `address`, `mail_from_address`, `default_currency`, `default_locale`, `url`, `support_email`, `logo_url`, `logo_width`, `branding`
+- `store.branding`: `background_color`, `card_color`, `text_color`, `heading_color`, `accent_color` (empty unless the merchant set one), `link_color`, `button_color`, `button_text_color`, `button_border`, `font`, `font_family`, `heading_font_family`, `font_url` (a web font's stylesheet, empty for email-safe fonts)
### `order`
diff --git a/docs/developer/customization/emails.mdx b/docs/developer/customization/emails.mdx
index 2af4919e19..4a5b86c9fa 100644
--- a/docs/developer/customization/emails.mdx
+++ b/docs/developer/customization/emails.mdx
@@ -9,7 +9,7 @@ Every email Spree sends — order confirmations, shipping notices, password rese
To change an email, you copy its template into your app and edit it. Nothing else changes: Spree still picks the recipient, the language and the sender, and delivers the email through your [SMTP provider](/developer/providers/emails).
<Note>
- Templates read plain data — the same fields the [Store API](/api-reference/store-api/introduction) returns, plus what only an email needs — never Ruby objects. The same template can later run outside Ruby, and merchants will be able to edit templates safely from the dashboard.
+ Templates read plain data — the same fields the [Store API](/api-reference/store-api/introduction) returns, plus what only an email needs — never Ruby objects. The same template can run outside Ruby, and merchants can edit customer emails safely from the dashboard.
</Note>
## Where templates live
@@ -104,6 +104,73 @@ In development and test, a variable that does not exist raises an error instead
To look at every email with real data, open the mailer previews at `/rails/mailers` on your Spree server.
+## Templates merchants edit in the dashboard
+
+Merchants can edit the emails their customers receive in **Settings → Emails → Templates**, along with the layout and the shared blocks in `spree/shared`. An edit is saved as a draft and goes live when published; publishing renders it with the store's own data first and refuses a template that does not render. Staff, store-owner and seller emails are not editable and always render from files.
+
+A store's published template comes first, so the lookup for an editable email is:
+
+1. the store's published template in the email's language
+2. the store's published template for every language
+3. your app's file
+4. Spree's file
+
+Your file stays the default the dashboard starts from and reverts to, so overriding a template in code and letting merchants edit it work together. When a Spree upgrade or a change to your file alters a default a merchant has customized, the dashboard tells them and shows what changed.
+
+The same operations are open to integrations through the [Admin API](/api-reference/admin-api/introduction), with the `email_templates` permission:
+
+<Tabs>
+ <Tab title="Admin SDK">
+ ```typescript
+ const preview = await client.emailTemplates.preview('spree.order_mailer.confirm_email', {
+ body: '<mj-section><mj-column><mj-text>Thanks, {{ order.customer_name }}!</mj-text></mj-column></mj-section>',
+ })
+
+ await client.emailTemplates.draft.update('spree.order_mailer.confirm_email', {
+ body: '<mj-section><mj-column><mj-text>Thanks, {{ order.customer_name }}!</mj-text></mj-column></mj-section>',
+ })
+ await client.emailTemplates.publish('spree.order_mailer.confirm_email')
+ ```
+ </Tab>
+ <Tab title="cURL">
+ ```bash
+ curl -X PUT https://your-store.com/api/v3/admin/email_templates/spree.order_mailer.confirm_email/draft \
+ -H "X-Spree-Api-Key: sk_xxx" -H "Content-Type: application/json" \
+ -d '{"body": "<mj-section><mj-column><mj-text>Thanks, {{ order.customer_name }}!</mj-text></mj-column></mj-section>"}'
+
+ curl -X POST https://your-store.com/api/v3/admin/email_templates/spree.order_mailer.confirm_email/publication \
+ -H "X-Spree-Api-Key: sk_xxx"
+ ```
+ </Tab>
+</Tabs>
+
+### Branding
+
+Merchants set the colors and font of their customer emails in **Settings → Emails**, without touching a template. Templates read them from [`store.branding`](/developer/customization/email-variables#store), and Spree's layout uses them throughout. If you override the layout or a template, read colors and fonts from `store.branding` rather than writing them in, so a store's branding keeps applying.
+
+### Making your own customer email editable
+
+A customer email your app adds can be edited like Spree's own. Register it with a class that builds the data its preview renders with:
+
+```ruby server/config/initializers/spree.rb
+Rails.application.config.after_initialize do
+ Spree.editable_email_templates.register(
+ 'spree/review_mailer/request_email', kind: :email, sample: 'ReviewRequestSample'
+ )
+end
+```
+
+```ruby server/app/services/review_request_sample.rb
+# Previews with the store's latest completed order, or the one the merchant picks.
+class ReviewRequestSample < Spree::Emails::Samples::Order
+ def variables
+ { order: super[:order], review_url: placeholder_url('reviews/new') }
+ end
+end
+```
+
+A sample builds from the record the merchant picked, else the store's latest one; a store with none is told there is nothing to preview with yet. Pass placeholder URLs, never real tokens, and register only emails your customers receive.
+
## Your own mailers
A mailer that inherits `Spree::BaseMailer` and renders its own ERB views with `mail` keeps working. Spree wraps its HTML in the same layout as every other email, so it carries the store's logo, header and footer. The `spree/shared/mailer_hero` and `spree/shared/mailer_button` partials are still there for those views.
diff --git a/docs/plans/6.0-email-template-editor.md b/docs/plans/6.0-email-template-editor.md
index 597944fb40..2af088db7c 100644
--- a/docs/plans/6.0-email-template-editor.md
+++ b/docs/plans/6.0-email-template-editor.md
@@ -1,6 +1,6 @@
# Email Template Editor
-**Status:** Design finalized — nothing built
+**Status:** In Progress — backend, Admin API, admin SDK and branding built; dashboard editor and docs in progress on `feature/v-3729-email-template-editor`
**Target:** Spree 6.0
**Depends on:** `6.0-liquid-mjml-emails.md` (Liquid and MJML templates, the template lookup, email serializers), `6.0-admin-rbac.md` (permission catalog), `6.0-admin-spa.md` (dashboard)
**Author:** Damian Legawiec
@@ -30,7 +30,8 @@ Every transactional email Spree sends renders from a Liquid template written in
- **History is the live row plus an append-only revisions table** (2026-09-30). `spree_email_templates` holds what is published, so the lookup on every send is one indexed read; `spree_email_template_revisions` records each publish. Rejected: one versions table with a current flag, which makes every send query the latest version and needs the flag kept consistent under concurrent publishes.
- **Reverting keeps the row, marked reverted, so history survives** (2026-10-01). A published template has a `status` (`published` or `reverted`, declared with `has_status`); reverting to the default sets it to `reverted` and deletes the draft. The lookup reads only `published` rows, and publishing again later reuses the same row, so its revisions stay reachable. Rejected: deleting the row, which made the email's history unreachable from its screen.
- **Drafts carry a version number and who saved them last** (2026-10-01). `lock_version` refuses a save made from a stale copy (409), and `updated_by` lets the editor say "Last saved by Ann, 5 minutes ago" and name who changed the draft in that refusal. One shared draft per store, email and language stays; two admins editing at once get a clear conflict instead of silently overwriting each other.
-- **Preview uses the latest matching record, and the merchant can pick another** (2026-09-30). Each email builds its sample from the store's most recent matching record (last completed order, fulfillment, return), falls back to an in-memory sample for a new store, and accepts a record id so a merchant can check a specific case (a discount, a multi-parcel order).
+- **Preview uses the latest matching record, and the merchant can pick another** (2026-09-30). Each email builds its sample from the store's most recent matching record (last completed order, fulfillment, return) and accepts a record id so a merchant can check a specific case (a discount, a multi-parcel order).
+ - **Superseded in part (2026-10-01):** emails built from a record (orders, order groups, fulfillments, returns) have no in-memory fallback. A store with no such record gets a clear "nothing to preview with yet" message instead of a preview, and publishing such an email checks its Liquid syntax only. Emails that need no record (password reset, newsletter confirmation, company invitation, data export) always preview. An invented order would need every serializer to accept unsaved records, which they do not.
- **Test emails go only to the signed-in admin** (2026-09-30). The endpoint cannot be used to send store-branded mail, a phishing risk, to arbitrary addresses. To check another inbox, the admin forwards it.
- **The editor is CodeMirror 6** (2026-09-30), as a headless `CodeEditor` component in `@spree/dashboard-ui` so the seller panel and plugins can reuse it. It is modular and small, and custom completions for Liquid variables and MJML tags are straightforward. Liquid highlighting inside HTML needs a small custom mode. Rejected: Monaco (a multi-megabyte bundle with web workers, poor on mobile) and a plain textarea (no highlighting or autocomplete).
- **The subject is a field of its own.** Files carry the subject as front matter; a saved template stores `subject` and `body` separately, which is the shape the front matter was chosen to map onto. The editor shows the subject as a text field above the code.
@@ -39,6 +40,13 @@ Every transactional email Spree sends renders from a Liquid template written in
- **Autocomplete reads a TypeScript manifest built on generated types; there is no variables API** (2026-10-01). Typelizer, added to `spree_emails`, generates TypeScript types for the email serializers (`EmailOrder`, `EmailOrderGroup`, `EmailFulfillment`, `EmailReturn`, the email store, …) into `@spree/admin-sdk`, and the existing pipeline turns them into Zod schemas. A hand-written manifest in the dashboard maps each editable email and shared block to the variables it receives and their schema; the editor walks the schemas to offer fields. The preview response also returns the data it rendered with, so autocomplete shows real example values at no extra cost.
- **Accepted trade-off:** the manifest's list of which variables each email receives is kept in step with its mailer by hand. Field types cannot drift, because they are generated. An extension adding a customer email registers its manifest entry through a dashboard plugin.
+- **The template remembers the default it started from as text, not a digest** (2026-10-01). Drafts and published versions store `base_subject` and `base_body`. Comparing them with the current file tells the editor the default changed, and keeping the text lets it show what changed side by side. There is no separate endpoint for the comparison: reading a template returns the current default and, when it changed, the base. A merchant who has reviewed the change keeps their version by saving the draft with `rebase`. Rejected: a SHA-256 digest, which says that something changed but not what.
+- **The API names a template by its key with dots** (2026-10-01), `spree.order_mailer.confirm_email` for `spree/order_mailer/confirm_email`. Keys never contain dots, so the mapping is exact, and a key stays one URL segment without percent-encoding slashes.
+- **The language is the `language` parameter, not `locale`** (2026-10-01). `locale` already picks the language of an API response, so reusing it would switch the response's language too, and `any` is not a language. Responses name the template's language `language` and the customized ones `customized_languages`. A per-language version is only accepted in a language the store supports.
+- **The editable registry lives in core** (2026-10-01), as `Spree.editable_email_templates`, with `spree_emails` registering its eleven customer emails, the layout and five shared partials, each with the class that builds its sample data. The Admin API, which does not depend on `spree_emails`, reads the registry rather than the gem.
+- **Branding is edited through the store settings endpoint and permission** (2026-10-01). The six branding values are store preferences (`preferred_email_accent_color`, `_background_color`, `_card_color`, `_text_color`, `_heading_color`, `_font`), so they are read and written with the other store settings and need the settings permission, not the email templates one. Only a `#RRGGBB` color or a font from the fixed list is accepted, and anything else falls back to the default before it reaches an email's CSS, unsaved preview values included. The preview takes unsaved `branding` values, so the branding card can show them before they are saved.
+- **Email data types have no Zod schemas** (2026-10-01). The `Email*` types are generated into their own folder of `@spree/admin-sdk` (`types/generated/emails`), which the Zod generator does not read: the order email's schema is too large for TypeScript to emit declarations for, and nothing validates email data at runtime. Autocomplete combines the hand-written manifest, typed against these types, with the variables the preview returns.
+
## Design Details
### Data model
@@ -50,9 +58,10 @@ id id id
store_id → spree_stores store_id → spree_stores email_template_id → spree_email_templates
key string, not null key string, not null subject text
locale string, not null locale string, not null body text, not null
-subject text subject text base_digest string, not null
-body text, not null body text, not null published_by (acted_by)
-base_digest string, not null base_digest string, not null created_at
+subject text subject text subject text
+body text, not null body text, not null body text, not null
+base_subject text base_subject text published_by (acted_by)
+base_body text, not null base_body text, not null created_at
status string, not null lock_version integer, not null index (email_template_id, created_at)
published_at datetime, not null updated_by (acted_by)
published_by (acted_by) created_at, updated_at
@@ -65,7 +74,7 @@ unique (store_id, key, locale) unique (store_id, key, locale)
- **`key`** is the name the lookup uses: an editable email's view path (`spree/order_mailer/confirm_email`), the layout (`layouts/spree/base_mailer`) or a partial's render name (`spree/shared/line_item`). It is validated against the editable set and what Spree and the app ship, so a store cannot create a template nothing renders or a staff email it may not edit.
- **`locale`** is a language code, or `'any'` for the version every language uses.
- **`subject`** is set for emails and empty for the layout and partials.
-- **`base_digest`** is the SHA-256 of the default file's source when the merchant started from it. Comparing it with the current default's digest is how the dashboard knows an upgrade changed the default underneath the merchant's version.
+- **`base_subject` and `base_body`** are the default file's subject and body when the merchant started from it. Comparing them with the current default is how the dashboard knows an upgrade changed the default underneath the merchant's version, and shows what changed.
- **Drafts** hold work in progress, one per store, key and language. Publishing validates the draft, copies it into `spree_email_templates` (creating the row on first publish), appends a revision and deletes the draft.
- **`status`** is `published` or `reverted` (`has_status`; set by the publish and revert workflows, no column default). **Reverting to the default** marks the row `reverted` and deletes the draft, so the file answers again; publishing later sets it back to `published` on the same row. **Reverting to a revision** copies it into the draft; the merchant publishes it like any other change. History is never rewritten.
- **`lock_version`** is Rails' optimistic locking on drafts. A save carrying an old version is refused with 409, naming `updated_by`.
@@ -73,7 +82,7 @@ unique (store_id, key, locale) unique (store_id, key, locale)
### Lookup
-An editable-email registry names the customer emails, `Spree::Emails.editable_templates` in `spree_emails`, which an extension appends to for its own customer emails. When a mailer renders one of them, `Spree::Emails::TemplateResolver#find(key)` gains a store:
+An editable-email registry names the customer emails, `Spree.editable_email_templates` in core, which `spree_emails` fills and an extension appends to for its own customer emails. When a mailer renders one of them, `Spree::Emails::TemplateResolver#find(key)` gains a store:
1. the store's `published` template for the key in the email's language
2. the store's `published` template for the key with `locale = 'any'`
@@ -95,21 +104,20 @@ Store preferences, all optional, defaulting to today's design:
### Admin API
-Under `/api/v3/admin/email_templates`, keyed by the template key (URL-encoded), scoped to the current store:
+Under `/api/v3/admin/email_templates`, keyed by the template key with dots, scoped to the current store. `language` (a language code, or `any`, the default) picks the version.
| Endpoint | What it does |
| --- | --- |
-| `GET /email_templates` | Every editable template: key, name, kind (email, layout, partial), languages customized, whether a draft exists, whether the default changed since |
-| `GET /email_templates/:key?locale=` | The published version (the store's, else the default), the draft if any (with `lock_version` and who saved it last), and the default |
-| `PUT /email_templates/:key/draft` | Save the draft's subject and body, in any state; carries `lock_version`, 409 naming who changed it when stale |
-| `DELETE /email_templates/:key/draft` | Discard the draft |
-| `POST /email_templates/:key/publication` | Publish the draft; renders it (and, for the layout or a partial, every customer email) with sample data; 422 with line-level errors when anything does not render |
-| `DELETE /email_templates/:key?locale=` | Revert to the default (marks the published row `reverted`) |
-| `POST /email_templates/:key/preview` | Render an unsaved subject and body with sample data (`record_id` optional); returns subject, HTML, text and the variables it rendered with |
-| `POST /email_templates/:key/test_email` | Send the draft or the published version to the signed-in admin |
-| `GET /email_templates/:key/revisions` | History, newest first |
-| `POST /email_templates/:key/revisions/:id/restoration` | Copy a revision into the draft |
-| `GET /email_templates/:key/default_diff` | The default as it was when customized, and as it is now |
+| `GET /email_templates` | Every editable template: key, kind (email, layout, partial), what customers receive now, the languages customized, the draft, whether the default changed since |
+| `GET /email_templates/:id` | The published version (the store's, else the default), the draft if any (with `lock_version` and who saved it last), the default, and the base it started from when the default changed |
+| `PUT /email_templates/:id/draft` | Save the draft's subject and body, in any state; carries `lock_version`, 409 naming who changed it when stale; `rebase` marks it as based on the current default |
+| `DELETE /email_templates/:id/draft` | Discard the draft |
+| `POST /email_templates/:id/publication` | Publish the draft; renders it (and, for the layout or a partial, every customer email) with sample data; 422 with each problem's email, line and message when anything does not render |
+| `DELETE /email_templates/:id` | Revert to the default (marks the published row `reverted`, discards the draft) |
+| `POST /email_templates/:id/preview` | Render an unsaved subject and body with sample data (`record_id`, `email_key` for the layout and partials, unsaved `branding`); returns subject, HTML, text and the variables it rendered with; 422 when it does not render or there is nothing to preview with |
+| `POST /email_templates/:id/test_email` | Send what the preview renders to the signed-in admin |
+| `GET /email_templates/:id/revisions` | History, newest first |
+| `POST /email_templates/:id/revisions/:revision_id/restoration` | Copy a revision into the draft |
Publish, preview, test send and restore are not CRUD on the template itself, so each is its own nested resource with `create`, per the API conventions.
@@ -131,7 +139,7 @@ All copy goes through i18next in every locale file, per the dashboard rules.
## Migration Path
1. **Models and lookup**: `Spree::EmailTemplate`, `Spree::EmailTemplateDraft`, `Spree::EmailTemplateRevision`, one migration, the store and language steps in `TemplateResolver`, publish and revert workflows with validation, lifecycle events, permission catalog entry `email_templates`.
-1a. **Email types**: Typelizer in `spree_emails`, an email writer emitting `Email*` types into `@spree/admin-sdk`, Zod schemas through the existing pipeline, and the Lefthook hook extended to the email serializers.
+1a. **Email types**: Typelizer in `spree_emails`, an email writer emitting `Email*` types into `@spree/admin-sdk`'s `types/generated/emails`, type generation for every SDK run from `spree_emails` so both serializer sets always load, and the Lefthook hook extended to the email serializers.
2. **Sample data and preview**: per-email sample builders, the preview and test email endpoints.
3. **Admin API**: the remaining endpoints, serializers, integration specs, OpenAPI regeneration, Admin SDK methods.
4. **Branding**: store preferences, `store.branding` in the store serializer, the default layout reading them, the branding card.
@@ -146,8 +154,10 @@ All copy goes through i18next in every locale file, per the dashboard rules.
- **Changing a default template triggers the "updated by Spree" banner** for every store that customized it. Change defaults deliberately, and describe the change in release notes.
- **Keep partial arguments stable.** Merchants can edit partials and the emails that call them independently, so renaming or removing a partial's argument breaks stores that customized either side. Add arguments; don't rename them.
- **Any new way to send an email must go through the lookup.** A mailer that renders a template itself would skip the store's published version.
-- **A new customer email must be registered as editable** in `Spree::Emails.editable_templates` (with a sample builder) and in the dashboard's variables manifest, or merchants cannot edit it. A new staff, store-owner or seller email must not be registered.
+- **A new customer email must be registered as editable** in `Spree.editable_email_templates` (with a sample builder) and in the dashboard's variables manifest, or merchants cannot edit it. A new staff, store-owner or seller email must not be registered.
- **Changing what a customer email passes to `mail_template` means updating its manifest entry**, and `email-variables.mdx`. Changing an email serializer regenerates its types through the pipeline.
+- **Run type generation through `rake typelizer:generate`, never Typelizer directly.** It runs inside `spree_emails`' test app, the one place where the API and email serializers both load; generating with either set missing deletes the other's types.
+- **Keep hard-coded colors and fonts out of customer email templates.** Read them from `store.branding`, so a store's branding reaches every email, including ones added later.
## Open Questions
diff --git a/docs/plans/decisions.md b/docs/plans/decisions.md
index f736c785f3..694d882a17 100644
--- a/docs/plans/decisions.md
+++ b/docs/plans/decisions.md
@@ -99,6 +99,16 @@ Rejected:
**Plans amended:** `6.0-tax-provider.md` (contract, Internal refund limit, "Post-sale tax", lifecycle integration points, Phase 6 follow-ups, Constraints on Current Work), `6.0-returns-exchanges-claims.md` (key decisions, ReturnLineItem, ExchangeLineItem and ClaimLineItem notes, refunding, exchange workflow, Constraints on Current Work, resolved question 7).
+## 2026-10-01: Building the email editor settled its API shape, branding and sample data
+
+**Context:** Implementing `6.0-email-template-editor.md` met details the design left loose: how the API names a template and its language, how the editor shows what an upgrade changed in a default, where branding is edited, what a new store previews, and whether the generated email types get Zod schemas.
+
+**Decision:** The API names a template by its key with dots (`spree.order_mailer.confirm_email`) and picks the version with a `language` parameter, because `locale` already sets the response's language. Templates and drafts store the default they started from as `base_subject` and `base_body`, so the editor can show what changed; reading a template returns the default and the base, with no separate diff endpoint, and saving a draft with `rebase` keeps the merchant's version as based on the new default. The editable registry is `Spree.editable_email_templates` in core, filled by `spree_emails`. Branding is six store preferences edited through the store settings endpoint under the settings permission; only `#RRGGBB` colors and fonts from a fixed list reach an email, and the preview takes unsaved values. Emails built from a record have no in-memory sample: a store with no such record is told there is nothing to preview with yet, and publishing such an email checks its syntax only. The `Email*` types are generated into their own folder of `@spree/admin-sdk` without Zod schemas, since the order email's schema is too large for TypeScript to emit and nothing validates email data at runtime.
+
+**Consequences:** Type generation for every SDK now runs from `spree_emails`, where both the API and email serializers load. A brand-new store cannot preview its order emails until it has an order. The earlier entry's Zod schemas for email types and the in-memory fallback for previews no longer apply.
+
+**Plans amended:** `6.0-email-template-editor.md`.
+
## 2026-10-01: The email editor's variables come from generated types, and reverted templates keep their history
**Context:** Building the email template editor (`6.0-email-template-editor.md`) left three details open: how autocomplete learns each email's variables, how two admins editing one draft avoid overwriting each other, and what reverting to the default does to a template's history.
diff --git a/docs/user/settings/emails.mdx b/docs/user/settings/emails.mdx
index 32277605eb..73a64dcef5 100644
--- a/docs/user/settings/emails.mdx
+++ b/docs/user/settings/emails.mdx
@@ -1,11 +1,9 @@
---
title: "Emails"
-description: "Learn how to set the addresses your store's transactional emails come from, who replies reach, and the logo shown at the top."
+description: "Learn how to set the addresses your store's transactional emails come from, brand them with your colors and font, and edit what they say."
---
-Spree sends transactional emails automatically as orders move: confirmations, shipping notifications, refunds and password resets. This screen controls the addresses behind those emails, who is told when an order comes in, and the logo at the top of each one.
-
-Email wording and layout are handled separately by your developers, who set the templates. What you control here is where mail comes from and where replies land, which is what customers actually judge when a message arrives.
+Spree sends transactional emails automatically as orders move: confirmations, shipping notifications, refunds and password resets. This screen controls the addresses behind those emails, who is told when an order comes in, the logo at the top of each one, and the colors and font they use. Under **Templates** you can change what each email your customers receive says.
To configure email settings, navigate to **Settings → Emails**, under the **Store** group.
@@ -39,11 +37,63 @@ Drop an image into the upload area or click to browse. Spree recommends **204 by
<Note>A transparent background matters more here than elsewhere, because email clients render backgrounds differently and a logo with a white box around it will look wrong against a coloured header.</Note>
+## Branding
+
+The colors and font of every email your customers receive. Changing them restyles all of those emails at once, without editing any template, and they stay when you revert a template to Spree's default.
+
+- **Accent color** - Buttons and links. Leave it empty to keep Spree's outlined buttons. Button text turns black or white, whichever reads better on your color.
+- **Background color** - Around the email.
+- **Card color** - Behind the email's content.
+- **Text color** and **Heading color** - Body text, and headings and amounts.
+- **Font** - Choose from fonts that display well in email apps. Web fonts, like Roboto, fall back to a similar standard font in email apps that do not load them.
+
+The preview next to the card shows your order confirmation with the colors and font you picked, before you save them.
+
## Saving Changes
Click **Save** at the top of the page. The button stays greyed out until you change something.
+## Templates
+
+Open the **Templates** tab to change what your customers' emails say and how they are laid out. You can edit:
+
+- each email your customers receive, such as the order confirmation, shipping notification, refund and password reset
+- the **layout** around every customer email, with the logo at the top and the footer
+- **shared blocks** used by several emails, such as an order's item rows and totals
+
+Emails sent to your team and to sellers are not editable here.
+
+<Note>Editing templates needs the **Email templates** permission, which is separate from store settings, because a template changes what every customer receives.</Note>
+
+### Editing a template
+
+Templates are written in [MJML](https://mjml.io) with Liquid placeholders, like `{{ order.number }}`, which Spree fills in for each email. As you type, the editor suggests the placeholders the email can use, and the preview shows the email filled in with one of your store's real orders. Switch the preview between desktop and mobile, or to the plain-text version that some email apps show. To check a particular case, such as an order with a discount, enter that order's ID in **Preview with record**.
+
+Changes are saved as a **draft**. Customers keep receiving the published version until you click **Publish**, and the editor always says whether you are looking at the draft or the published version. If someone else on your team saved the draft after you opened it, Spree tells you who, so you do not overwrite their work.
+
+Click **Send test email** to receive the email at your own address before publishing it.
+
+### Publishing
+
+**Publish** makes the draft what customers receive from the next email on. Spree first fills the template in with your store's data, and refuses to publish one that does not work, such as a misspelled placeholder, with the line to fix. When you publish the layout or a shared block, Spree checks every customer email that uses it.
+
+### Languages
+
+A template applies to every language your store sells in. To word one language differently, choose it in the language switcher and edit that version; the other languages keep using the shared one.
+
+### History and reverting
+
+Every published version is kept. Open **History** to see who published each one and when, and restore one into the draft to publish it again.
+
+**Revert to default** goes back to Spree's own template and discards the draft. Your earlier versions stay in the history.
+
+### When Spree updates a template
+
+When an update to Spree changes a template you have edited, the editor shows **Updated by Spree** with what changed. Compare the two versions, then keep yours or start again from the new default, and publish the result.
+
## Further Reading
- [<u>Policies</u>](/user/settings/policies) - The terms and privacy documents linked from your emails and storefront
+- [<u>Roles</u>](/user/settings/roles) - Who can edit email templates
+- [<u>Email Templates</u>](/developer/customization/emails) - How your developers customize templates in code
- [<u>Sending out Emails</u>](/developer/deployment/emails) - How your developers configure delivery and customise templates
diff --git a/spree/emails/app/services/spree/emails/samples/base.rb b/spree/emails/app/services/spree/emails/samples/base.rb
index a72ae768ff..178c5bf83a 100644
--- a/spree/emails/app/services/spree/emails/samples/base.rb
+++ b/spree/emails/app/services/spree/emails/samples/base.rb
@@ -29,7 +29,7 @@ module Spree
# @return [String] the currency the email's amounts are in
def currency
- self.class.record_type ? record.currency : store.default_currency
+ (self.class.record_type && record.try(:currency)).presence || store.default_currency
end
protected