# 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](/docs/learn/sending#schedule-a-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`:

```json
{
  "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

- [List templates](/docs/api/templates/list) Find a template ID by name or status.
- [Retrieve a template](/docs/api/templates/retrieve) Read its published version, including the variables a send uses.
- [List template variables](/docs/api/templates/variables) Read the variables of the version being edited.
- [List template versions](/docs/api/templates/versions) Read every saved and published version.

Reading templates requires an API key with `email.full_access`.

---

Source: https://connect.nxiom.com/docs/learn/templates