Transactional emails (transactional_emails)
Admin-editable transactional emails. Lets operators change the subject, content, and look of every transactional email the platform sends — globally and per Sales Channel — from the Admin UI, using an email-client-safe WYSIWYG editor consistent with the CMS Page Builder. Each email is described by a definition registered by the module that owns it (orders, returns, organizations, inventory, …), which supplies a default subject + default content and the set of variables the business logic substitutes at send time.
Concepts
- Definition — a registered email identified by a unique
code(e.g.order_confirmation). Carries the owning module, declared variables (with sample values for preview), supported languages, and the module-provided default subject + content. Reconciled intotransactional_emailsat boot; orphaned definitions (owning module uninstalled) are pruned. - Content — the admin's per-scope, per-language customization, stored in
transactional_email_contents. Resolution at send time is per-channel → global → module default, with a fallback to the channel's default language. Absence of a row means "fall back"; Reset deletes it. - Blocks & Templates — reusable email-safe fragments. Blocks are embedded by
codeviaEmailInsertBlock. Email templates remain a separate admin list (apply/save outside the canvas);EmailInsertTemplateis withdrawn from the palette (legacy trees still render). The seeded system blocksdefault_email_header(renders branding viaEmailLogo/{{var branding.logoUrl}}) anddefault_email_footerare auto-included in the default content. A system block or template cannot be deleted:DELETE /api/v1/admin/transactional-emails/blocks/:idanswers409 TRANSACTIONAL_EMAIL_SYSTEM_BLOCK(details:blockId,blockCode) andDELETE /api/v1/admin/transactional-emails/templates/:idanswers409 TRANSACTIONAL_EMAIL_SYSTEM_TEMPLATE(details:templateId,templateCode), with a sentence in the operator's language. Both were409 VALIDATION_FAILEDuntil issue #638. - Branding — header logo, accent color, and the default header/footer block
codes, resolved per scope through the Settings module
(
transactional_emails.*). The resolved logo is exposed to every email as{{var branding.logoUrl}}. - Variables — Magento-2-style directives over the content + subject:
{{var path}},{{if path}}…{{/if}},{{for alias in list}}…{{/for}}. Values are HTML-escaped in the HTML body and raw in the plain-text alternative. A missing value resolves to empty — an email is never sent with an unresolved{{…}}and a missing variable never fails a send. The admin editor exposes an Insert variable picker (subject, plain text fields, and rich text toolbar) fed by the email's declared variables plus branding keys.
Email editor
The transactional (and newsletter) editors share EmailEditorPane:
- Screen layout. The transactional editor is laid out in the shell every Page
Builder editor shares (
PageBuilderEditorLayoutfrom@endora-commerce/page-builder-admin): the canvas takes the full editor width, and one row above it carries the Scope (all channels, or one sales channel's override), the Language and the Subject. Unlike the CMS and blog editors it has no collapsible settings panel — those three say which message is on the canvas or are part of it, so they are never hidden. The e-mail block and e-mail template editors use the same shell with the Language alone. - Email-safe Puck palette from
@endora-commerce/email-components(no CMS breakpoints / responsive stacking). Row opens a column-layout picker (1–6 columns) like CMS; columns use a fixed table at send time and the CMS 12-col grid on the canvas. Column is not listed in the palette (only inside Row). Table is the data grid (headers + rows, like CMS SimpleTable). - The canvas is fixed at mail width (600px), with an Outline panel like CMS.
Use Preview email for a modal HTML render with sample variable data and
Desktop mail (600px) / Narrow (320px) options (fluid
max-width:600pxshell so narrow preview does not overflow). Save as template / Apply template reuse the CMS header actions against transactional email templates (email_templates). EmailLogoshows the branding logo (no URL field).EmailImagesupports URL or asset library, same as CMS. Color fields use the shared CMS color palette. Branding logo in Settings (*_asset_id) uses the Assets Library picker.EmailRichTextreuses the CMS Rich content TipTap editor (plus Variable).EmailProductCardpicks a catalog product;EmailOrderSummaryis column/totals toggles and appears in the palette only when the email declaresorder.items(today: Order confirmation only). Order confirmation also exposes labeled detail blocks: Order ID, Billing/Shipping address, Summary, Applied discounts, Delivery method, Payment method (each gated on its template variable).- Content blocks include layout (
EmailSection,EmailRow/EmailColumn, table, spacer, divider), copy (EmailText,EmailRichText, headings, callout, footer/legal), media (EmailImage,EmailLogo), commerce (EmailProductCard,EmailOrderSummaryand the order detail blocks above),EmailSocial(icons + labels + per-link enable), andEmailInsertBlock.
Rendering
Rendering is performed server-side by the first-party @endora-commerce/email-components
package (React-free): the Puck content tree is walked and emitted as
table-based, inline-styled, email-client-safe HTML plus a plain-text
alternative. The admin editor reuses the same email-safe component palette.
EmailRichText HTML is whitelist-sanitized (p/strong/em/u/a/ul/ol/li/br)
before send; directive markers in text are preserved.
Registering an email from a module
// manifest.ts
transactionalEmails: [
{ code: 'order_confirmation', name: 'Order confirmation', group: 'orders',
variables: [{ key: 'order.businessId', label: 'Order number', sampleValue: 'ORD-1042' }] },
],
// plugin.ts (default subject + content)
emailDefaultsRegistry.register('order_confirmation', { defaultSubject, defaultContent });
A variable's sampleValue is English. When the sample reads differently in another
language — an address, a status — add sampleValueKey, a key in the declaring module's own
bundles (relative to its namespace, like a palette action's labelKey) holding the sample in
every shipped language, the English entry equal to sampleValue. The editor's variable list
and live preview, and the server preview, show the sample in the language being edited; the
manifest's sampleValue answers when the key does not resolve.
The owning module sends through the TransactionalEmailSender port (injected by
composition), preserving its existing idempotency messageId:
await sender.send({
code: 'order_confirmation',
salesChannelId, language, to,
messageId: `order_confirmation:${order.id}`,
variables: { order: { businessId, items: [...] }, customer: { firstName } },
});
When the sender is not wired, modules fall back to their legacy in-code builders, so behavior is unchanged in environments without the module.
A module that also keeps an in-code fallback resolves templateEmailPort instead, whose
trySend answers false only when no definition exists for the code. It takes the same
code, to, messageId and variables, and optionally the recipient's salesChannelId and
language: the message is rendered from that channel's content in that language. A missing or
deleted channel renders on the system-default channel, and a missing language in the channel's
default language, so a caller that names neither gets the system-default channel in its default
language. The back-in-stock e-mail passes the channel and language the subscription recorded.
Preview
POST /api/v1/admin/transactional-emails/{code}/preview renders an email with
each variable's declared sample value (and any unsaved draft content), returning
{ subject, html, text }. The admin opens the HTML in a new tab.
Switching an email off
The module itself is non-deactivatable: every deployment sends account
verification, invitations and order mail through it, so /platform/modules
renders it locked with that reason rather than as a toggle. The granularity that
is offered is the individual email — the list at /transactional-emails
carries a per-row switch, backed by
POST /api/v1/admin/transactional-emails/{code}/activation with { active }.
The flip runs through the Command Bus, so it is audited as
transactional_email.activation.set and reversible; it drops no content, no
override and no per-channel customization. A deactivated email answers
{ status: 'deactivated' } at send time and no fallback mail goes out.
Emails required to create an account or to get back into one may not be switched
off at all: today email_verification and organization_invitation. The
declaration lives on the owning module's registry entry
(EmailDefaults.nonDeactivatable), not in a list held by this module or by the
Admin UI, and a refused flip answers 409 TRANSACTIONAL_EMAIL_NOT_DEACTIVATABLE
carrying that module's own reason — the same shape the module-level refusal uses.
Delivery record
Every send leaves one row in email_deliveries, a table owned by the email
module — the transport is where a message's fate is decided, so it is where the
record of that fate lives. The row carries the recipient, the email code, the
sales channel, the message id, the business document the message delivered (an
invoice, typically), the outcome and the moment it was attempted.
The outcome is one of four, and the split is the point of the table:
| Status | Means | Typical reason |
|---|---|---|
sent | a mail server accepted the message | — |
logged | no mail server is configured (SMTP_URL is unset), so the message was only written to the server log and reached nobody | — |
suppressed | the platform deliberately did not send | deactivated (an operator switched this email off), duplicate_message_id |
failed | the message was meant to go out and did not | transport_error, no_transport, no_definition |
An operator asking "did the customer get the invoice" therefore gets an answer
that outlives a log rotation, and one that does not confuse a configuration they
chose with an outage. A logged message is never reported as sent: the sender
answers logged to the module that asked, so an invoice issued on an instance
without a mail server says its email was not sent, and a reminder that would have
gone to the bell and by email is recorded as delivered to the bell alone. This is best-effort delivery with a durable record, not
guaranteed delivery: there is no retry queue and no outbox, a resend stays an
operator action, and a message lost between the business write and the transport
call is lost. There is no admin screen over the table yet — it is read from the
database.
When a customer account is anonymised, the customers module asks email
(emailDeliveryAnonymizationPort) to scrub every record addressed to that
account's address, compared case-insensitively: the recipient becomes the
anonymised marker and the subject, the envelope and the transport's error text
are cleared, while the message id, email code, status, reason, sales channel,
document reference and attempt time stay. Each scrubbed record gets one
email_delivery.anonymized audit entry.
Permissions
transactional_emails:read— view emails, blocks, templates, branding, preview.transactional_emails:write— edit content, branding, and manage blocks/templates.
Registered emails
All pre-existing transactional emails route through this mechanism: orders
(confirmation, comment, reorder, admin-created), returns (authorized, rejected),
organizations (verification, invitation, new-registration, approved, rejected), and inventory
(low-stock, back-in-stock). Two net-new emails are also registered and dispatched
via event subscribers: payments (payment_status_changed, on payment
received/failed) and shipments (shipment_created, on shipment created).
Other modules register their own: carts (cart_approval_requested,
cart_approved, cart_rejected), invoices (invoice_issued), quote requests
(quote_request_pdf and the eleven quote_request_customer_* /
quote_request_operator_* notification emails), CRM (crm_event_reminder),
projects (projects_stage_deadline_alert) and tasks (tasks_task_reminder,
tasks_daily_digest). Which of them an instance lists depends on the modules it
has installed.