Templates
A template is an email you save once and send many times. It has a subject, an HTML body, an optional text body and variables that you fill in when you send.
Templates are managed through the API. They belong to your account, so a test key and a live key can both use them.
Create a template
POST /v1/templates takes these fields. No other fields are accepted.
| Field | Required | Notes |
|---|---|---|
name | Yes | 1 to 100 characters. For your reference. |
subject | Yes | One line, up to 998 characters. May contain variables. |
html | Yes | The HTML body, up to 400,000 characters. |
text | No | The plain text body. If you leave it out, Darzus writes one from the HTML when you send. |
curl https://darzus.com/v1/templates \
-H "Authorization: Bearer $DARZUS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Receipt",
"subject": "Receipt for order {{order_id}}",
"html": "<p>Thanks for your order, {{first_name}}.</p>"
}'
The response is 201 Created, with the template's ID, its variables and its version:
{
"id": "tpl_01jd3k5m7p8h2x6q4r9t",
"name": "Receipt",
"subject": "Receipt for order {{order_id}}",
"html": "<p>Thanks for your order, {{first_name}}.</p>",
"text": null,
"variables": ["order_id", "first_name"],
"version": 1,
"created_at": "2026-11-12T14:03:22.410Z",
"updated_at": "2026-11-12T14:03:22.410Z"
}
Darzus finds the variables for you. The list in variables covers the subject, the HTML and the text.
Variables
A variable is a name in double braces, such as {{first_name}}. A name starts with a letter or an underscore, and can contain letters, numbers, underscores and dots.
{{name}}is replaced with the value, escaped for HTML. Use it for anything a reader sees as text.{{{name}}}is inserted exactly as given. Use it only for HTML you trust, because it is not escaped.
Values can be strings, numbers or booleans. In the subject and the text part, values are inserted as given.
Send a template
Send a template with the template field of POST /v1/emails. Give its id and the values for its variables. Leave out html and text, because the template supplies the body.
curl https://darzus.com/v1/emails \
-H "Authorization: Bearer $DARZUS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": "Example Shop <hello@example.com>",
"to": "ada@example.com",
"template": {
"id": "tpl_01jd3k5m7p8h2x6q4r9t",
"variables": { "order_id": "1042", "first_name": "Ada" }
}
}'
A subject in the request replaces the template's subject. Otherwise the template's subject is used.
If a variable used by the template has no value, the request returns 422 with validation_error. The message names the missing variable, and nothing is sent.
Change a template
PUT /v1/templates/{id} replaces the template. It takes the same fields as the create call, so send the full subject and HTML each time. Each save raises version by one. Emails that were already sent are not changed.
GET /v1/templates lists your templates, and GET /v1/templates/{id} returns one. A template that belongs to another account returns 404.
Try a template with a test key
Send the template with a test key first. The email is kept as caught mail, and GET /v1/emails with the same key lists it, so you can check the rendered HTML and the text part before you switch to a live key. See Test mode.