Templates

A template is a stored subject, HTML and text body with declared variables. POST /templates creates one, GET /templates/{id} reads it, and a send references it instead of carrying the body.

Variables are declared, not inferred

A template names the variables it expects. A render missing a required variable the template uses is refused rather than silently producing "Hello ," — the empty greeting is the single most common defect in transactional mail and it is entirely preventable at the API boundary.

Markdown becomes HTML and text

A markdown template is sent as HTML with a plain-text part made from the same source: headings, paragraphs, bold and italic, links, images, lists, quotes and code. A single line break stays a line break. HTML typed into the markdown is shown as text, variable values are never read as markdown, and links go only to https://, http:// or mailto: addresses. Write the template in HTML mode when you need your own markup.

A template's source can be up to 512 KB, and so can a broadcast's own body or an automation's email step. Anything larger is refused when you save it, with the field named.

Always ship a text part

A template with HTML and no text alternative is scored worse by most filters and is unreadable in a client that refuses HTML. The text part is not a formality.

An email sent with html and no text gets a text part made from the HTML: tags removed, each link written as its text followed by the address in brackets, & and the other entities decoded, and runs of spaces collapsed. Pass text to write it yourself, or text: "" to send the HTML alone.

Versions

Editing a template creates a version rather than overwriting one. A message records the version it rendered, so a mail a customer forwards you six weeks later can be reproduced exactly as they received it.

Preview before you send

POST /templates/{id}/render returns the rendered subject, HTML and text for a set of variables without sending anything. Use it in your own tests: a template that stops rendering is a defect you want at build time. Pass "preview": true to render before you have sample values: a missing variable shows as its own placeholder, such as {{first_name}}, and is listed in missing_variables instead of failing.

Deleting a template

DELETE /templates/{id} removes a template and its versions. Mail already sent keeps its body and still names the template and version it came from. While a broadcast that has not been sent uses the template, the delete is refused and names the broadcast; archive it first.

What templates do not do

They do not personalise beyond substitution, and there is no list-building or audience import attached to them. If a feature would make sending to people who did not ask easier, it is not here.