- List every template and language as an explicit review matrix.
- Render previews with the same components used for real messages.
- Use fictional, repeatable examples including difficult edge cases.
- Keep preview pages isolated and available only to authorised Admin users.
- A correct preview proves rendering, not event selection or delivery.
The client needed to review rare messages without manufacturing incidents
Medusa lets a project trigger notifications, and React Email lets it build the message components. Neither automatically gave the client’s team one inventory of every project-specific template and locale with stable review data. Rare emails were therefore the easiest to miss during a release.
We built a registry of templates, pre-rendered static HTML during the backend build and exposed it through an authorised Medusa Admin page. Deterministic fixtures made routine and low-frequency messages reviewable across four locale variants, while delivery monitoring remained focused on events, provider submission and inbox outcomes.
Why email review was unnecessarily difficult
To review an order confirmation, someone had to place an order. To review a password email, they had to request a reset. Rare templates such as cancellations or stock alerts were easily forgotten. Every additional language multiplied the manual work. As a result, emails could be technically present in the code yet receive little product or editorial review.
The client needed product, content, support and localisation colleagues to inspect all transactional messages from Medusa Admin. The goal was not to build a second email system. Production templates remained the source. The Admin feature simply made their rendered output easy to browse with safe sample data.
Make the complete template-and-language matrix visible
The system maintains a registry listing each template, human-readable name, supported languages and sample scenarios. The Admin page calculates the expected combinations from this registry. It does not rely on a manually typed claim such as ‘20 previews’, which becomes wrong when a template or language is added.
Missing combinations fail visibly. If one template intentionally does not support a language, the exception needs a reason. Order confirmation deserves no more structural visibility than shipment, refund, password recovery or waitlist email. The matrix turns coverage into something the whole team can inspect rather than knowledge hidden in a templates folder.
Use the real rendering components
During the build, the application renders templates with known fictional data and stores the resulting HTML. The Admin page displays those artefacts. This reuses the same email components as production without shipping the rendering engine to the browser or contacting the email provider.
Because inputs are deterministic—fixed names, dates, products and identifiers—a code change produces a meaningful difference. Random values would create noise in every review. Generated previews must be rebuilt whenever templates, shared styles, translations or sample contracts change. If one template throws an error, the build should fail rather than publish a blank frame that reviewers mistake for an empty email.
One cheerful example is not enough
A normal one-line order does not reveal long German labels, a ten-item basket, missing company name, a large refund, right-to-left Arabic or a broken image. We create named scenarios for branches that matter: employee discount, pickup delivery, tracking information, payment failure and optional address fields.
Fixtures remain fictional and internally consistent. When production reveals a new structural edge case, add an anonymised shape—not customer data—to the scenario library. Review currencies, date formats, pluralisation, address order, links, alt text and the message’s meaning when images are blocked. Transactional email quality is commerce correctness as well as layout.
Treat the preview as an internal security boundary
The backend accepts only known template and language values and returns the matching generated artefact. It does not turn request parameters into arbitrary file paths. The route requires Admin authentication, and failures distinguish an unknown template, unsupported language and missing build output.
The HTML appears in an isolated frame so template styles do not break Medusa Admin. Scripts are unnecessary and should remain blocked. Links and forms should not accidentally perform live customer actions. Sample data must never contain customer addresses, tokens or internal hostnames. ‘Internal tool’ is not a reason to relax validation.
What a preview proves—and what it does not
A correct preview proves that one registered template can render with sample data and that an authorised reviewer can retrieve it. It does not prove that the correct business event chooses that template, that real order data satisfies its requirements, that public links work, that the provider accepts the email or that an inbox receives it.
Those boundaries need separate checks: tests connecting order events to template data, validation of public links, provider sandbox or disposable-inbox tests and monitoring of rejection, bounce and complaint rates. Browser width controls are helpful, but they do not reproduce every Gmail or Outlook behaviour. The preview is one strong layer in a larger release process.
Turn previews into a release workflow
Engineering owns safe rendering and the data contract. Content owners approve wording and hierarchy. Localisation reviewers validate meaning and market conventions. Operations verifies that real events select the expected message and delivery evidence exists. Approvals belong to a template revision, not a screenshot that can outlive the code.
When a shared layout changes, affected approvals should be reopened across the matrix. High-risk payment and security messages deserve real workflow fixtures and delivery smoke tests. This division of responsibility turns an attractive Admin page into a practical quality control shared by technical and non-technical teams.
The transactional email checklist
Inventory templates and languages, register deterministic scenarios, add risk-based edge cases, render with production components, fail on missing output, authenticate the endpoint, isolate the frame and validate every public link. State clearly what each test proves.
Before release, review the changed templates and every market they affect. Connect the template revision to the workflow revision supplying its data. After release, monitor provider and inbox outcomes by template and language. The objective is not merely to make email HTML visible; it is to make transactional communication reviewable from code change to customer receipt.
Common questions
It reuses production components, creates repeatable artefacts, catches rendering errors before deployment and avoids using customer data or contacting the provider.
At least one normal scenario plus every edge case that changes meaning or layout: long content, optional fields, discounts, refunds, market formats and right-to-left language where relevant.
No. It proves rendering with sample data. Event selection, real payloads, public links, provider acceptance and inbox delivery require additional tests.