Templates

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 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

See for the personalization model and for styling.

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 an unfinished edit never reaches a recipient. 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. 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. shows them in the Courier app, and 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 :

const { requestId } = await client.send.message({
  message: {
    to: { email: 'sarah@acme-corp.com' },
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
    data: { invite_url: 'https://www.acme-corp.com/invite' },
  },
});

response = client.send.message(
    message={
        "to": {"email": "sarah@acme-corp.com"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "data": {"invite_url": "https://www.acme-corp.com/invite"},
    },
)

curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "email": "sarah@acme-corp.com" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "data": { "invite_url": "https://www.acme-corp.com/invite" }
    }
  }'

response = courier.send_.message(
  message: {
    to: { email: "sarah@acme-corp.com" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: { invite_url: "https://www.acme-corp.com/invite" }
  }
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				Email: courier.String("sarah@acme-corp.com"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data: map[string]any{
			"invite_url": "https://www.acme-corp.com/invite",
		},
	},
})

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("email", "sarah@acme-corp.com")))
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of("invite_url", "https://www.acme-corp.com/invite")))
        .build())
    .build();
client.send().message(params);

$response = $client->send->message(
  message: [
    'to' => ['email' => 'sarah@acme-corp.com'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'data' => ['invite_url' => 'https://www.acme-corp.com/invite'],
  ],
);

SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { Email = "sarah@acme-corp.com" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "invite_url", JsonSerializer.SerializeToElement("https://www.acme-corp.com/invite") },
        },
    },
};

await client.Send.Message(parameters);

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message '{"to":{"email":"sarah@acme-corp.com"},"template":"nt_01kx4h2jdafq8bk9aftxak4b40","data":{"invite_url":"https://www.acme-corp.com/invite"}}'

With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to sarah@acme-corp.com with the invite URL.

That template field accepts either form:

Value	Looks like	Where it comes from
Template ID	`nt_01kx4h2jdafq8bk9aftxak4b40`	Generated by Courier, shown in the template’s settings
Alias	`order-confirmation`	A name you assign, in the template’s settings under Alias

An alias is the readable name your code keeps while the template behind it changes. You assign one in the template’s settings, under Alias, not over the API. It then sits exactly where the ID sat, and nothing else about the request changes. Three rules govern them:

A template can have many aliases. Old and new names can both resolve during a rename.
An alias points at one template at a time. Moving it to another template repoints every send that uses that name.
An alias works anywhere the ID works. Nothing else in the request changes.

That second rule is the useful one. Repointing an alias switches the content behind a send with no deploy, and it switches it for every caller at once.

Limits & behavior

A send uses the published version. Unpublished edits stay in the draft until you publish.
Runs and logs are version-pinned. A message records the template version it rendered, so history stays accurate after later publishes.
The designer and API share one template. Editing in one is visible in the other. There is no separate “API template.”

FAQ

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 is not overwritten.

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?

Assign an alias and pass it as template on the send, so your code references a human-readable name instead of the generated ID.

Get started

Send messages

Journeys

Broadcasts

Design

Recipients

Tenants

Monitoring

Workspaces

Resources

Which one to use

Design a template

Template API

How it works

Draft, publish, and version history

How a template is performing

Send it by ID or alias

Limits & behavior

FAQ

​Which one to use

Design a template

Template API

​How it works

​Draft, publish, and version history

​How a template is performing

​Send it by ID or alias

​Limits & behavior

​FAQ

Which one to use

How it works

Draft, publish, and version history

How a template is performing

Send it by ID or alias

Limits & behavior

FAQ