Skip to main content
A template defines what a notification says, how it looks, and how it behaves across channels. You build it once, then send it through email, SMS, push, chat, or in-app. A template is Elemental content plus channel, routing, and brand settings. Build it visually in the designer, or as code through the Templates API.

Which one to use

A template built in the designer and one managed through the API are the same object, and it is Elemental content either way. The difference is where your team would rather work.

Design a template

Build it in the visual editor: drag-and-drop blocks, per-channel content, test-data previews, and version history.Best when PMs, designers, and developers work on content together.

Template API

Manage it as JSON: create, update, and publish from your codebase, review changes in Git, and test payloads in CI.Best when templates live in code, or you would rather not click through a UI.

How it works

Beyond content, a template carries the settings that shape a send:
  • Channels it can go out on
  • Reusable routing, primary and fallback
  • A Brand for consistent styling
  • Conditional logic to show or hide content by data or preference
  • Variables that personalize each recipient’s version
  • Translations so each recipient gets their language
See variables & Handlebars for the personalization model, brands for styling, and template translations for languages.

Draft, publish, and version history

Editing a template updates its draft. Publishing snapshots the draft as the active version. A normal send renders the published version, so recipients never see an unfinished edit. Version history lets you compare versions side by side and roll back. A message’s log records the version it used, so you can trace a rendering change to a publish. Go live covers reviewing a draft before you publish it.

How a template is performing

Sends, deliveries, opens, clicks, and errors are reported per template, split by channel and provider. Analytics shows them in the Courier app, and template metrics returns the same series over the API for your own dashboards.

Send it by ID or alias

Both paths end the same way. Pass the Template ID and the data its variables need to POST /send:
That template field accepts either form: An alias is the readable name your code keeps while the template behind it changes. Over the API, setting notification.alias to null clears it, and leaving it out keeps the existing alias. Four rules govern them:
  • A template has one alias. Setting a new one replaces the old one, and sends that still use the old name end UNMAPPED.
  • An alias belongs to one template. Assigning an alias another template holds returns 409, so clear it there first, by setting that template’s alias to null.
  • An alias works anywhere the ID works. Nothing else in the request changes.
  • An alias can’t start with tenant/. That prefix is reserved for tenant templates, and the API rejects it with 400.
Moving an alias to another template switches the content behind a send with no deploy, for every caller at once.

FAQ

Both operate on the same template. One team can edit in the designer while another manages it through the API. Coordinate publishes so a draft edit isn’t overwritten.
Edits go to the draft. Publishing makes the draft the active version. Normal sends render the published version.
Assign an alias and pass it as template on the send, so your code references a human-readable name instead of the generated ID.