Templates

A template is an email you design in the dashboard under Templates - text, headings, buttons, images, a verification code - and then send from your code with its id and a few values:

{
  "to": "priya@example.com",
  "template": {
    "id": "welcome",
    "variables": {
      "first_name": "Priya",
      "dashboard_url": "https://app.acme.com/dashboard"
    }
  }
}

The subject, the HTML and the plain-text part all come from the template. So do From and Reply-To, unless you pass your own - anything set on the request wins over the template.

template.id is the template's slug (shown under its name, and editable in the builder) or its uuid.

Variables

Write {{name}} anywhere in a template - in text, the subject, the preview text, a button's link, an image address - and pass name in template.variables when you send.

• Values are always inserted as text. <b>Priya</b> arrives as those characters, not as bold - there is no way to inject markup through a variable.
• A link that is entirely a variable ({{reset_url}}) is checked when it is filled in: it must be an https://, http:// or mailto: address, or the send is refused.
• Each variable can have a fallback, used when you don't pass it (first_name → "there"). A variable with no fallback that you don't pass refuses the send with a validation_error naming it - better than an email that says "Hi ,".
• Sample values are only for the preview and test emails in the dashboard.

Publishing

The builder saves as you type, but sends always use the published version - a half-finished edit never reaches your users. Publish when it's ready; until a template has been published, sending with it is refused.

Publishing checks that the From address is on one of your verified domains and that there is a subject and some content, so a template that publishes is one that can actually go out.

Every publish is kept under History, where you can preview any version and restore it into the draft. Restoring doesn't change what's sent until you publish again.

Test emails

Test email sends the current draft, with the sample values, to up to five addresses. It's a real send: it goes through the usual checks and counts towards your plan.

Batch

Each message in a batch can name a template, and templates are looked up once per batch. A problem with one message's template fails the whole batch, the way other validation errors do, and the error says which message it was.