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.

FieldRequiredNotes
nameYes1 to 100 characters. For your reference.
subjectYesOne line, up to 998 characters. May contain variables.
htmlYesThe HTML body, up to 400,000 characters.
textNoThe 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.