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
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 toPOST /send:
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 tonull. - 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 with400.
FAQ
Can I manage a template in code and in the designer?
Can I manage a template in code and in the designer?
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.
What is the difference between a draft and a published template?
What is the difference between a draft and a published template?
Edits go to the draft. Publishing makes the draft the active version. Normal sends render the published version.
Can I reference a template by a stable name?
Can I reference a template by a stable name?
Assign an alias and pass it as
template on the send, so your code references a human-readable name instead of the generated ID.