Templates
Design an email once, publish it, and send it by ID with your own values.
A template holds a subject, HTML and plain-text content, and the variables they use. Design and publish templates in the dashboard under Email → Templates, then send one with its ID. Read templates over the API to find IDs and the values each one needs.
Drafts and published versions
Editing a template changes its draft. Sends always use the published version, so you can work on a draft without affecting emails that are already going out.
| Status | Meaning | Can send |
|---|---|---|
draft | Never published. | No |
published | Published, with no unpublished changes. | Yes |
changes_in_draft | Published, with a newer draft. Sends use the published version. | Yes |
archived | Archived. | No |
Each publish creates a new version. The version an email used is fixed when you send it, even when you publish again before a scheduled send goes out.
Variables
A template uses variables as {{variable_name}} in its subject and content. Names start with a lowercase letter and use lowercase letters, digits, and underscores, such as first_name or trial_days.
| Field | Meaning |
|---|---|
key | The variable name to use in templateVariables. |
type | string or number. A number value must be numeric. |
required | A required variable needs a non-empty value in every send. |
fallback_value | Used when an optional variable is not provided. |
Values in HTML are escaped. Values you send for names the template does not define are ignored.
Send a template
Send with templateId and templateVariables instead of subject, html, and text:
{
"from": "hello@mail.example.com",
"to": "reader@example.com",
"templateId": "YOUR_TEMPLATE_ID",
"templateVariables": {
"first_name": "Sam",
"trial_days": 14
}
}The send returns 400 without sending when the template does not exist in the API key's project, has never been published, or is archived, or when a required variable is missing or a number variable is not numeric.
Find a template and its variables
Reading templates requires an API key with email.full_access.