Templates

​

Writing one

{
  "id": "0199f1f0-2d3e-7f4a-8b5c-6d7e8f9a0b12",
  "alias": "order-shipped",
  "name": "تم شحن الطلب",
  "state": "published",
  "published_version": 3,
  "published": {
    "id": "0199f200-3d4e-7f5a-8b6c-7d8e9f0a1b23",
    "number": 3,
    "state": "published",
    "subject": "طلبك {{ ORDER }} في الطريق",
    "html": "<p>مرحبًا {{ NAME }}، طلبك {{ ORDER }} في الطريق.</p>",
    "text": null,
    "from": null,
    "reply_to": [],
    "variables": [
      {
        "key": "ORDER",
        "fallback": null
      },
      {
        "key": "NAME",
        "fallback": "عميلنا"
      }
    ],
    "placeholders": [
      "ORDER",
      "NAME"
    ],
    "problems": [],
    "published_at": "2026-10-23T09:00:00+00:00",
    "updated_at": "2026-10-23T09:00:00+00:00"
  },
  "draft": null,
  "created_at": "2026-10-20T09:00:00+00:00",
  "updated_at": "2026-10-23T09:00:00+00:00"
}

• {{ KEY }} is replaced by the value, HTML-escaped in html; {{{ KEY }}} places it as is, in html only. Keys are letters, digits and _, starting with a letter or _. There are no sections, loops, conditions or partials. Values are placed once: a value holding {{ OTHER }} is sent as that text.
• A template has a draft and numbered published versions. Sends use the published version; POST /v1/email/templates/{id}/publish makes the draft the next one, and a restore copies an older version into the draft.
• Send by template with template: {"id": "<id or alias>", "variables": {…}} on POST /v1/email/messages and on each item of a batch. html and text are then refused; subject overrides the template’s; from and reply_to come from the request, else the version, else the domain’s defaults. A missing variable takes its fallback, else 422 template_variable_missing; an undeclared one answers 422 template_variable_unknown.
• The message is rendered when it is accepted: the size check, the idempotency fingerprint and the kept copy see the rendered message, and the message records the template and the version it used. A retry with the same Idempotency-Key after a new version was published answers what the first call answered.
• Over SMTP, the headers X-Tawked-Template: <id or alias> and X-Tawked-Template-Variables: <a JSON object> send by template; a variables header that is not a JSON object (or is over 16 KiB) is refused with 550 5.7.1 template_variables_invalid.
• "version": "draft" sends the draft: test keys only.

​

Sending by template

{
    "from": "orders@acme.sa",
    "to": "sara@example.com",
    "template": {
        "id": "order-shipped",
        "variables": {
            "ORDER": "1042",
            "NAME": "سارة"
        }
    }
}