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

# Broadcast templates

> Write the content of a broadcast as template versions, publish the one to send, and personalize it for each recipient and each broadcast.

A template holds the content of your broadcasts. You write that content as versions, publish the one you want to use, and each broadcast sends one specific version.

> [!NOTE]
>
> Templates need an API key with the `broadcast` permission. See [Set up Broadcast](https://nuntly.com/docs/guides/broadcast-setup.md#api-key-permissions).

## Templates and versions

A template has a name and a list of versions. You [create a template](https://nuntly.com/docs/api-reference/templates/create-template.md), then [create versions](https://nuntly.com/docs/api-reference/templates/create-template-version.md) in it.

A version holds:

| Field | Required | Description |
| - | - | - |
| `subject` | Yes | The subject line, up to 200 characters. |
| `html` | Yes | The HTML body. |
| `text` | No | The plain-text body. Without it, the message has no plain-text part. |
| `variables` | No | The [declared variables](#declared-variables) the content uses. |

A version cannot be edited once it exists. To change the content, create a new version. Earlier versions stay available, so you can go back to one. Each create request makes a new version, even when the content is the same as an existing one.

You can [read the HTML and text of a version](https://nuntly.com/docs/api-reference/templates/retrieve-template-version-content.md) at any time.

## Publish a version

Publishing makes a version the active one of its template. New broadcasts use the active version. To go back to an earlier version, publish it again.

A template is `draft` until you publish its first version, then `published`.

The content is checked when you publish. A version is refused when:

* it uses a `{{...}}` token that is not supported. See [Personalization](#personalization).
* the HTML has no [unsubscribe link](https://nuntly.com/docs/guides/broadcast-unsubscribe.md#the-unsubscribe-token). A text body, when there is one, needs it too.
* it references a contact property your organization has not defined, or a variable the version does not declare.
* it is too large, or references too many contact properties.

The [API reference](https://nuntly.com/docs/api-reference/templates/publish-template-version.md) lists the error returned for each case.

## Personalization

Personalization lets one version produce a different message for each recipient and each broadcast. You place tokens in the subject, the HTML, or the text. Each token is replaced when the message is sent.

```html theme={null}
Subject: What's new on the {{contact.Plan}} plan

<p>Use the code {{promo}} before Friday.</p>
<p><a href="{{system.unsubscribeUrl}}">Unsubscribe</a></p>
```

| Token | Replaced by | Changes with |
| - | - | - |
| `{{contact.Plan}}` | The value of a [contact property](#contact-properties) for this recipient | Each recipient |
| `{{contact.email}}` | The address of this recipient | Each recipient |
| `{{promo}}` | The value of a [declared variable](#declared-variables), set on the broadcast | Each broadcast |
| `{{system.unsubscribeUrl}}` | The unsubscribe link of this recipient. Required in the body, not allowed in the subject | Each recipient |

Any other `{{...}}` construct, such as a Handlebars helper or block, is not supported.

### Contact properties

Write `{{contact.PropertyName}}` with the exact name and letter case of a [contact property](https://nuntly.com/docs/guides/broadcast-segments.md#contact-properties) defined in your organization. `{{contact.Plan}}` and `{{contact.plan}}` are two different properties.

When a recipient has no value for the property, the default value of its definition is used, or an empty value when there is no default.

### Declared variables

A declared variable holds a value that changes with each broadcast rather than with each recipient, such as a promo code or an event date. Do not put sensitive data in it, such as health data or religious beliefs.

You declare variables when you create a version, each with a name, a type (`string`, `number`, or `boolean`), and an optional default value. Reference one in the content by its name alone, for example `{{promo}}`.

Each broadcast supplies its own values. A variable with no value on the broadcast uses its default, and sending is refused when there is neither. See [Personalization variables](https://nuntly.com/docs/guides/broadcast-sending.md#personalization-variables).

## What a broadcast sends

A broadcast sends one version of its template.

* When you create a broadcast, it uses the active version of the template at that moment.
* Publishing a new version later does not change a broadcast that already uses a version. To move a `draft` or `scheduled` broadcast to the new active version, set its template again.
* When the template had no active version yet, the broadcast uses the version that is active when it is sent. For a scheduled broadcast, that is when the schedule fires.
* The subject of the broadcast, when you set one, replaces the subject of the version.

Once the broadcast is `queued`, its content and settings can no longer change. See [Create and send a broadcast](https://nuntly.com/docs/guides/broadcast-sending.md).

## Delete a template

Deleting a template deletes its versions. You cannot delete a template while any broadcast, including a sent one, uses it or one of its versions.

## Next steps

> [card] [Create and send a broadcast](https://nuntly.com/docs/guides/broadcast-sending.md)
>
> Bind a template to a broadcast and send it

> [card] [Unsubscribe and suppression](https://nuntly.com/docs/guides/broadcast-unsubscribe.md)
>
> The unsubscribe link that the placeholder becomes


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