> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tawked.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Templates

> Hosted e-mail templates: variables with fallbacks, a draft and numbered versions, publishing and restoring, and sending by id or alias over the API and SMTP.

A template keeps a message's subject, HTML and text with placeholders, so your code sends only the values. Templates are an application's, written in the console (**Email → Templates**) or by API with a live key that manages Email. At most 100 an application (Tawked's limit).

## Writing one

```json theme={"dark"}
{
  "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.

| Call | What it does |
| - | - |
| `GET /v1/email/templates` | Lists them, without their HTML and text. |
| `POST /v1/email/templates` | Creates one as a draft, or published with `"publish": true`. |
| `GET /v1/email/templates/{id}` | Reads one, by id or alias, with its published version and its draft. |
| `PATCH /v1/email/templates/{id}` | Changes its draft. |
| `POST /v1/email/templates/{id}/publish` | Publishes the draft as the next version. |
| `GET /v1/email/templates/{id}/versions` | Lists its published versions. |
| `POST /v1/email/templates/{id}/versions/{number}/restore` | Copies a version into the draft. |
| `DELETE /v1/email/templates/{id}` | Deletes it; its alias is free again. |

A template's `from` is written as a send's is: `{"name", "address"}`, `"orders@acme.sa"` or `"Acme <orders@acme.sa>"`; `null` leaves it to the request and the domain's defaults.

Publishing refuses with `422 template_invalid` and its `problems` while one is an error: a placeholder the variables do not declare, no subject, no content, HTML over 512 KiB, or a from address off the application's domains.

## Sending by template

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

A missing variable takes its fallback, else `422 template_variable_missing`; an undeclared one answers `422 template_variable_unknown`; a template that was never published answers `422 template_not_published`. [Sending email](https://docs.tawked.com/email/messages.md#errors) has every code.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.