Templates: four engines, and which one you actually want

01Four engines, one entry point

Everything that renders a message — the send path, broadcast fan-out, the dashboard preview — calls one function, renderTemplate, and nothing else. That is not tidiness for its own sake: it is the only way a template can be guaranteed to render identically in the preview you approved and in the broadcast that goes out an hour later. Two code paths would eventually be two behaviours.

Who edits this? If the answer includes anybody who does not want to see angle brackets, you want a structured document rather than a string, because only a structured document can be presented as a form. What runtime does it have to render on? If the answer is a Cloudflare Worker — which it is, for every send on a default deployment — then MJML is out, and that is a hard constraint rather than a preference.

02The structured AST, and its fifteen components

The jsx-ast engine is the one that sounds most exotic and is in practice the most boring, which is the point. You author a React-Email-shaped .tsx file; mailysend templates push runs it through a real parser on your machine, where a parser and a filesystem are entirely reasonable things to have; and what gets stored is a data-only JSON tree.

// welcome.tsx — what you write
<Container>
  <Preview>Your account is ready</Preview>
  <Heading level={1}>Hi {contact.first_name | default:"there"}</Heading>
  <Text>Two things to do first.</Text>
  <Button href={"{{ activation_url }}"}>Activate</Button>
</Container>

That split is the whole design. A template body is customer-controlled data that gets stored and later rendered inside a shared isolate on behalf of somebody else’s send, so anything in that path capable of evaluating an expression from the body is a sandbox escape waiting to be found.

Fifteen components make up the document. They are deliberately email components rather than web ones — there is no div, because a div is not how you lay out a message that has to survive Outlook.

03Handlebars, interpreted rather than compiled

This is a handlebars interpreter, not a handlebars compiler. Upstream handlebars compiles a template into a JavaScript function; this one parses the template into a tree and walks it.

Hi {{capitalize first_name}},

{{#if plan}}You are on the {{plan}} plan.{{/if}}

You have {{formatNumber credits}} {{pluralize credits "credit" "credits"}} left,
expiring {{formatDate expires_at "medium"}}.

{{#each items}}  · {{this.name}}
{{/each}}

The UTC default is not a shrug. A Worker’s clock is always UTC while a self-hosted Node box is whatever the operator set, and “the same broadcast rendered a different date depending on which runtime picked up the job” is a bug that only appears near midnight, in production.

04MJML, and the runtime it needs

MJML is supported and it is Node-only. The compiler needs Node APIs that Cloudflare Workers does not provide, so on a Worker the engine throws MjmlUnavailableError immediately rather than attempting a partial render.

// on a Worker:
MjmlUnavailableError: MJML cannot be compiled on Cloudflare Workers.
// Compile MJML before it reaches the send path: run `mailysend templates push`,
// which compiles it locally and uploads the HTML, or add an MJML build step in
// CI and store the compiled HTML on the template version.

Either way the send path receives plain HTML and nothing on the hot path depends on a Node-only dependency. If you are starting a template from scratch and want MJML’s layout guarantees without its runtime, the AST engine was designed for exactly this constraint.

05What happens to your HTML afterwards

Whichever engine produced it, the HTML then goes through a fixed post-render pipeline before it becomes a MIME message.

Common questions