Write the email once, publish a version
A template is a name, an optional alias and a series of versions of its content. Publishing freezes a version, sends use that one, and every email records exactly which version it used.
template order-shippedpublished
subject: Order {{order_id}} is on its way
variables: order_id number, name string
POST /emails
{ "template": {
"id": "order-shipped",
"variables": { "name": "Ronald", "order_id": 1042 }
} }
● The email records the version it used
What a versioned email template gives you
Content kept apart from the code that sends it, without losing the record of which content each message actually carried.
Publishing freezes a version
Creating a template writes version 1 as a draft. Publishing makes that version the one sends use, and the next edit opens a new draft without changing a thing about what goes out until you publish again.
Typed variables, checked at send
Each variable has a key, a type of string, number, boolean, object or list, and an optional fallback. A value of the wrong type is refused rather than rendered.
Send by ID or by alias
Every template route, and every send, takes the template's ID or its alias. An alias is lower case, unique among your live templates, and may never look like an ID, so the two can never be confused.
Every send records its version
The email keeps the template and the exact version it resolved, so a later edit never changes what an already-sent message said.
Preview before you publish
Render any version with sample values the way a send would, and get the subject, the HTML and the text back, along with any variable that had no value. Nothing is stored.
Reading a template works with any API key. Creating, updating, publishing, duplicating and deleting need a key with full access, and the whole catalogue of routes is on the templates reference.
How publishing a template changes what sends
Three moves, and only one of them changes what your customers receive.
- 1
Write the content and declare its variables
A version carries from, subject, reply_to, html and text, with {{key}} placeholders. Every placeholder must be declared, and every declared variable must be used, so a mistake comes back naming the key rather than as an email nobody can read.
- 2
Publish the version
Publishing makes the current version the one sends use. It takes effect for the next send; messages already queued keep the version they resolved. Publishing again when nothing has changed is allowed and does nothing.
- 3
Send it by ID or alias
Post an email with a template object and your values. The published version supplies the body, and the subject, sender and reply-to wherever the request leaves them out. Fields you do set on the request win.
A send names a template instead of carrying a body, so it cannot pass html or text at the same time. Everything else a send can do is unchanged: idempotency keys, batches, scheduling, attachments and tags all work exactly as they do on the email API page, and the request shape is in the emails reference.
The placeholder grammar is {{key}} and nothing else
Deliberately small. A template language with conditionals and filters is a second language to learn, document and support, and it is not one we ask you to take on.
A placeholder is a key in double braces, with spaces inside the braces allowed. Keys are letters, digits and underscores. A string is escaped where it lands in the HTML body and left as written in the subject and the text body; numbers and booleans are written out; objects and lists arrive as compact JSON. A value that itself contains braces is inserted as that literal text and never expanded, so a value out of your database cannot smuggle in another placeholder.
POST /templates
{ "name": "Welcome", "alias": "welcome", "subject": "Welcome, {{name}}", "html": "<p>Hello {{name}}, thanks for joining.</p>", "variables": [ { "key": "name", "type": "string", "fallback_value": "there" } ]}Both directions are checked when you write: every placeholder the bodies use must be declared, and every declared variable must be used, with one error for each key that is wrong so an editor can point straight at it. A version may declare up to two hundred variables. Preview renders a version with sample values and lists any that had no value, and the same interpolation runs in the dashboard editor and at send time, so what you see in the preview is what goes out.
Templates are for the mail your product sends one message at a time. Sending to an audience you own is the broadcasts page, and mail that goes out because something happened in your product is automations. The typed clients reach every template route as well: the Node SDK has a preview method, and the quickstart gets you to a first send before any of this matters.
Questions about email templates
What happens when I edit a published email template?
Nothing, until you publish again. The first edit after a publish opens a new draft and later edits write that same draft, while sends keep using the published version. Retrieving the template shows the draft, with has_unpublished_versions set to true so you can tell the two apart.
Can I send from a draft?
No. Only a published template can be sent, and naming one that has no published version in a send is refused with a 422 rather than sent from whatever the draft happens to say.
How do I address a template from my code?
By its ID or by its alias. An alias is lower case letters, digits, hyphens and underscores, up to 63 characters, unique among your live templates, and may never look like an ID, so a name like order-shipped is a stable handle your code can hold on to. Deleting a template frees its alias again.
What template syntax do you support?
{{key}}, with optional spaces inside the braces, and nothing else. There is no logic, no filters and no nesting, so a value that itself contains braces is inserted as that literal text rather than expanded. Strings are escaped in the HTML body and left raw in the subject and the text body.
What if a send leaves a variable out?
It takes the fallback declared on that variable. A declared variable with no value and no fallback is refused with a 422, and a key the template never declared is refused too, so an email does not go out with a placeholder still showing.
Does editing a template change emails I have already sent?
No. Each email records the template and the version it used, so what a customer received stays correct in your records however often you change the template afterwards.
Publish your first template
Write a template, publish it, and send it by alias with your values filled in.