Broadcast templates

A template holds the content of your broadcasts. The content itself lives in versions, and a broadcast sends one specific version.

​

Templates and versions

A template is a named container. You create it with a name and add content by creating versions. Renaming a template does not affect its versions. A version holds: A version is immutable. You cannot edit or delete it once it exists. To change the content, create a new version. Creating a version does not deduplicate. Sending the same request twice creates two versions. You can read the stored HTML and text of a version. Each field comes back as a short-lived download link, or as absent when the field was never stored, or as unavailable when it cannot be read right now.

​

Publish a version

Publishing checks the content and makes the version the active one of its template. The previous active version goes back to draft. It is not lost, and you can publish it again. Publishing refuses a version with a 422 response when the content breaks one of these rules, checked in this order:

• The subject, the HTML, and the text contain no unsupported {{...}} construct. The error code is template_version_placeholder_unsupported. See Personalization for what counts as supported.
• The HTML contains the unsubscribe token. When the text body is not blank, it contains the token too. The error code is template_version_unsubscribe_placeholder_missing.
• The subject, HTML, and text together stay under 750 KB. The error code is template_version_too_large.
• The content references at most 20 distinct contact properties. The error code is template_version_too_many_properties.
• Every bare variable token is declared by the version. The error code is template_version_undeclared_variable.
• Every referenced contact property, other than email, has a matching definition. The error code is template_version_undefined_property.

Publishing a version that is not a draft fails with a 409 response. If two publications for the same template race, the one that finishes second fails with a 409 response and you can retry it.

​

Personalization

Broadcast content can reference three kinds of tokens, all written {{...}}: Any other construct, such as a flat token, a Handlebars helper or block, a comment, a partial, triple braces, or a namespace keyword in the wrong letter case, is unsupported. Nuntly refuses it when you publish, with template_version_placeholder_unsupported. If such a construct reaches a send some other way, for example from content published before personalization existed, Nuntly strips it before rendering rather than failing the recipient.

​

Contact properties

Write {{contact.PropertyName}} using the exact name and letter case of a contact property definition of your organization. {{contact.email}} always works and renders the recipient’s address; it’s the only fixed contact field a token can read.

• The name is matched with its exact letter case. {{contact.Plan}} and {{contact.plan}} read two different properties if your organization defines both.
• At publish time, Nuntly checks that every referenced name, other than email, has a matching definition. An undefined name is refused with template_version_undefined_property.
• A version can reference at most 20 distinct contact properties across the subject, HTML, and text. More is refused with template_version_too_many_properties.
• When a recipient has no value for a property, Nuntly renders the property definition’s default, or a typed empty value (an empty string or 0) when there’s no default. When the organization no longer defines the property at send time, Nuntly renders an empty string.

​

Declared variables

A version can declare up to 20 variables: values that vary per broadcast rather than per recipient, such as a promo code or an event date. Declare them alongside subject, html, and text when you create the version. Reference a declared variable in content as a bare token, with no namespace prefix, for example {{promo}}. Declarations are fixed once the version is created: you cannot add, remove, or change one afterward. Every bare token in the content must match a declared name, or publishing is refused with template_version_undeclared_variable. A declared variable that no part of the content references is accepted; it just goes unused. Creating a version with an invalid declaration set is refused with a 422 response: A broadcast supplies the values for these variables when you create or edit it. See Personalization variables.

​

What a broadcast sends

A broadcast is bound to one version of a template. These rules decide which one.

• When you create a broadcast with a template, Nuntly binds it to the version that is active at that moment. When the template has no active version yet, the binding stays empty.
• Publishing a new version does not change the version of broadcasts that are already bound. While a broadcast is draft or scheduled, name the template on it again to bind the version that is active now.
• When the binding is still empty as you send, Nuntly binds the active version of the template at the moment the broadcast is accepted. For a scheduled broadcast, that moment is when the schedule fires.
• When you send, Nuntly checks the bound version again against the publication rules above, together with the subject of the broadcast. A failure returns a 422 response and the broadcast is not sent.
• A version that has since been replaced as the active version still sends when a broadcast is bound to it. Its content does not change.
• The subject of the broadcast wins when you set one. Otherwise the subject of the bound version is used.

The content freezes once the broadcast is accepted, which is when its status becomes queued. From then on the template, the version, the subject, the sender address, the reply-to address, the segment, and the topic of the broadcast can no longer change. Only a draft or scheduled broadcast can be edited. See Create and send a broadcast.

​

Delete a template

Deleting a template also deletes its versions. Nuntly refuses with a 409 response while any broadcast, in any status, references the template or one of its versions. A broadcast that has been accepted cannot be deleted, so the template of a queued, sending, paused, or sent broadcast cannot be deleted either.

​

Operations

​

Next steps