Manage templates with the API

explains the draft/publish model.

Manage templates over the API so they live in code and move through Git review. Each carries an nt_ ID and a draft/published lifecycle.

Prerequisites

Create a template

returns a new template in the DRAFT state:

const notificationTemplateResponse = await client.notifications.create({
  notification: {
    name: 'Welcome Email',
    tags: ['onboarding', 'welcome'],
    brand: { id: 'bnd_01kx4mrd0pfzw8wt7pn7p2fzag' },
    subscription: { topic_id: 'pt_01kx4h2jdafq8bk9a26x0kvd1t' },
    routing: { strategy_id: 'rs_01kx4h2jdafq8bk9amzvy6hbv0' },
    content: {
      version: '2022-01-01',
      elements: [
        {
          type: 'channel',
          channel: 'email',
          elements: [{ type: 'text', content: 'Welcome aboard, {{name}}.' }],
        },
      ],
    },
  },
  state: 'DRAFT',
});

notification_template_response = client.notifications.create(
    notification={
        "name": "Welcome Email",
        "tags": ["onboarding", "welcome"],
        "brand": {"id": "bnd_01kx4mrd0pfzw8wt7pn7p2fzag"},
        "subscription": {"topic_id": "pt_01kx4h2jdafq8bk9a26x0kvd1t"},
        "routing": {"strategy_id": "rs_01kx4h2jdafq8bk9amzvy6hbv0"},
        "content": {
            "version": "2022-01-01",
            "elements": [
                {
                    "type": "channel",
                    "channel": "email",
                    "elements": [{"type": "text", "content": "Welcome aboard, {{name}}."}],
                }
            ],
        },
    },
    state="DRAFT",
)

curl --request POST \
  --url https://api.courier.com/notifications \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "notification": {
      "name": "Welcome Email",
      "tags": ["onboarding", "welcome"],
      "brand": { "id": "bnd_01kx4mrd0pfzw8wt7pn7p2fzag" },
      "subscription": { "topic_id": "pt_01kx4h2jdafq8bk9a26x0kvd1t" },
      "routing": { "strategy_id": "rs_01kx4h2jdafq8bk9amzvy6hbv0" },
      "content": {
        "version": "2022-01-01",
        "elements": [
          {
            "type": "channel",
            "channel": "email",
            "elements": [{ "type": "text", "content": "Welcome aboard, {{name}}." }]
          }
        ]
      }
    },
    "state": "DRAFT"
  }'

notification_template_response = courier.notifications.create(
  notification: {
    brand: {id: "bnd_01kx4mrd0pfzw8wt7pn7p2fzag"},
    content: {elements: [{type: "channel", channel: "email", elements: [{type: "text", content: "Welcome aboard, {{name}}."}]}], version: "2022-01-01"},
    name: "Welcome Email",
    routing: {strategy_id: "rs_01kx4h2jdafq8bk9amzvy6hbv0"},
    subscription: {topic_id: "pt_01kx4h2jdafq8bk9a26x0kvd1t"},
    tags: ["onboarding", "welcome"]
  }
)

// The typed elemental model has no field for a channel's child elements, so pass the content as raw JSON.
content := param.Override[shared.ElementalContentParam](json.RawMessage(`{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "channel",
      "channel": "email",
      "elements": [{ "type": "text", "content": "Welcome aboard, {{name}}." }]
    }
  ]
}`))

notificationTemplateResponse, err := client.Notifications.New(context.TODO(), courier.NotificationNewParams{
	NotificationTemplateCreateRequest: courier.NotificationTemplateCreateRequestParam{
		Notification: courier.NotificationTemplateWritePayloadParam{
			NotificationTemplatePayloadParam: courier.NotificationTemplatePayloadParam{
				Brand: courier.NotificationTemplatePayloadBrandParam{
					ID: "bnd_01kx4mrd0pfzw8wt7pn7p2fzag",
				},
				Content: content,
				Name:    "Welcome Email",
				Routing: courier.NotificationTemplatePayloadRoutingParam{
					StrategyID: "rs_01kx4h2jdafq8bk9amzvy6hbv0",
				},
				Subscription: courier.NotificationTemplatePayloadSubscriptionParam{
					TopicID: "pt_01kx4h2jdafq8bk9a26x0kvd1t",
				},
				Tags: []string{"onboarding", "welcome"},
			},
		},
	},
})

NotificationTemplateCreateRequest params = NotificationTemplateCreateRequest.builder()
    .notification(NotificationTemplateWritePayload.builder()
        .brand(NotificationTemplatePayload.Brand.builder()
            .id("bnd_01kx4mrd0pfzw8wt7pn7p2fzag")
            .build())
        .content(ElementalContent.builder()
            // The channel builder has no addElement, so its children go in as an additional property.
            .addElement(ElementalChannelNodeWithType.builder()
                .type(ElementalChannelNodeWithType.Type.CHANNEL)
                .channel("email")
                .putAdditionalProperty("elements", JsonValue.from(java.util.List.of(
                    java.util.Map.of("type", "text", "content", "Welcome aboard, {{name}}."))))
                .build())
            .version("2022-01-01")
            .build())
        .name("Welcome Email")
        .routing(NotificationTemplatePayload.Routing.builder()
            .strategyId("rs_01kx4h2jdafq8bk9amzvy6hbv0")
            .build())
        .subscription(NotificationTemplatePayload.Subscription.builder()
            .topicId("pt_01kx4h2jdafq8bk9a26x0kvd1t")
            .build())
        .addTag("onboarding")
        .addTag("welcome")
        .build())
    .build();
NotificationTemplateResponse notificationTemplateResponse = client.notifications().create(params);

$notificationTemplateResponse = $client->notifications->create(
  notification: [
    'brand' => ['id' => 'bnd_01kx4mrd0pfzw8wt7pn7p2fzag'],
    'content' => ['elements' => [['type' => 'channel']], 'version' => '2022-01-01'],
    'name' => 'Welcome Email',
    'routing' => ['strategyID' => 'rs_01kx4h2jdafq8bk9amzvy6hbv0'],
    'subscription' => ['topicID' => 'pt_01kx4h2jdafq8bk9a26x0kvd1t'],
    'tags' => ['onboarding', 'welcome'],
  ],
  state: 'DRAFT',
);

NotificationCreateParams parameters = new()
{
    Notification = new()
    {
        Brand = new("bnd_01kx4mrd0pfzw8wt7pn7p2fzag"),
        Content = new()
        {
            // Elemental nodes expose no typed content property, so build the node from raw JSON.
        Elements =
        [
            ElementalChannelNodeWithType.FromRawUnchecked(
                JsonSerializer.Deserialize<Dictionary<string, JsonElement>>("""
                {
                  "type": "channel",
                  "channel": "email",
                  "elements": [{ "type": "text", "content": "Welcome aboard, {{name}}." }]
                }
                """)),
        ],
            Version = "2022-01-01",
        },
        Name = "Welcome Email",
        Routing = new("rs_01kx4h2jdafq8bk9amzvy6hbv0"),
        Subscription = new("pt_01kx4h2jdafq8bk9a26x0kvd1t"),
        Tags = ["onboarding", "welcome"],
    },
};

var notificationTemplateResponse = await client.Notifications.Create(parameters);

courier notifications create \
  --api-key "$COURIER_API_KEY" \
  --notification "{brand: {id: bnd_01kx4mrd0pfzw8wt7pn7p2fzag}, content: {elements: [{type: channel, channel: email, elements: [{type: text, content: 'Welcome aboard, {{name}}.'}]}], version: '2022-01-01'}, name: Welcome Email, routing: {strategy_id: rs_01kx4h2jdafq8bk9amzvy6hbv0}, subscription: {topic_id: pt_01kx4h2jdafq8bk9a26x0kvd1t}, tags: [onboarding, welcome]}"

With Courier MCP, create a draft template called Welcome Email tagged onboarding.

Content needs a channel to live in

Every element belongs inside a channel block. Content whose elements sit at the top level is rejected at creation:

{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "channel",
      "channel": "inbox",
      "elements": [{ "type": "text", "content": "Your order shipped." }]
    }
  ]
}

The channel block is what the renders when someone opens the template, so content without one is stored but opens as an empty document. A meta element may sit at the top level alongside the channel blocks. A template with no elements at all is fine: it is one nobody has written yet. Only creation is checked. Templates already saved without a channel block still send, and are left alone.

Read a template

returns the template, defaulting to the published version. Pass ?version=draft (or a version like v001) to read another:

const notificationTemplateResponse = await client.notifications.retrieve('nt_01kx4h2jdafq8bk9aftxak4b40');

notification_template_response = client.notifications.retrieve(
    id="nt_01kx4h2jdafq8bk9aftxak4b40",
)

curl --request GET \
  --url https://api.courier.com/notifications/nt_01kx4h2jdafq8bk9aftxak4b40 \
  --header "Authorization: Bearer $COURIER_API_KEY"

notification_template_response = courier.notifications.retrieve("nt_01kx4h2jdafq8bk9aftxak4b40")

notificationTemplateResponse, err := client.Notifications.Get(
	context.TODO(),
	"nt_01kx4h2jdafq8bk9aftxak4b40",
	courier.NotificationGetParams{},
)

NotificationTemplateResponse notificationTemplateResponse = client.notifications().retrieve("nt_01kx4h2jdafq8bk9aftxak4b40");

$notificationTemplateResponse = $client->notifications->retrieve('nt_01kx4h2jdafq8bk9aftxak4b40');

NotificationRetrieveParams parameters = new() { ID = "nt_01kx4h2jdafq8bk9aftxak4b40" };

var notificationTemplateResponse = await client.Notifications.Retrieve(parameters);

courier notifications retrieve \
  --api-key "$COURIER_API_KEY" \
  --id nt_01kx4h2jdafq8bk9aftxak4b40

With Courier MCP, show me the published version of my welcome email template.

Update content: the round-trip contract

Template content is read and written through a separate content endpoint. returns one of two shapes: the modern V2 elemental form ({ version, elements }, where every element carries a read-only checksum and a translated element carries its translations in locales) or the legacy V1 form ({ blocks, channels, checksum }).

PUT accepts V2 elemental only, and it replaces all content.
takes the { version, elements } tree inside a content object. Read the draft with ?version=draft, change the elements, and remove every checksum at any depth, because the write rejects them. Templates translated in Design Studio also carry keys starting with an underscore, such as _sourceHash, inside locales. Remove those too. Keep each element’s id and locales: an element sent without an id gets a new one, and one sent without locales loses its translations.

This example writes content to a template with no translations yet. To change only a template’s translations, write one locale at a time with , which leaves the default content and other locales as they are. See .

const notificationContentMutationResponse = await client.notifications.putContent('nt_01kx4h2jdafq8bk9aftxak4b40', {
  content: {
    version: '2022-01-01',
    elements: [
      {
        type: 'channel',
        channel: 'email',
        elements: [{ type: 'text', content: 'Welcome aboard, {{name}}.' }],
      },
    ],
  },
  state: 'DRAFT',
});

notification_content_mutation_response = client.notifications.put_content(
    id="nt_01kx4h2jdafq8bk9aftxak4b40",
    content={
        "version": "2022-01-01",
        "elements": [
            {
                "type": "channel",
                "channel": "email",
                "elements": [{"type": "text", "content": "Welcome aboard, {{name}}."}],
            }
        ],
    },
    state="DRAFT",
)

curl --request PUT \
  --url https://api.courier.com/notifications/nt_01kx4h2jdafq8bk9aftxak4b40/content \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "content": {
      "version": "2022-01-01",
      "elements": [
        {
          "type": "channel",
          "channel": "email",
          "elements": [{ "type": "text", "content": "Welcome aboard, {{name}}." }]
        }
      ]
    },
    "state": "DRAFT"
  }'

notification_content_mutation_response = courier.notifications.put_content(
  "nt_01kx4h2jdafq8bk9aftxak4b40",
  content: {elements: [{type: "channel", channel: "email", elements: [{type: "text", content: "Welcome aboard, {{name}}."}]}], version: "2022-01-01"}
)

notificationContentMutationResponse, err := client.Notifications.PutContent(
	context.TODO(),
	"nt_01kx4h2jdafq8bk9aftxak4b40",
	courier.NotificationPutContentParams{
		NotificationContentPutRequest: courier.NotificationContentPutRequestParam{
			// The typed elemental model has no field for a channel's child elements, so pass the content as raw JSON.
			Content: param.Override[courier.NotificationContentPutRequestContentParam](json.RawMessage(`{
			  "version": "2022-01-01",
			  "elements": [
			    {
			      "type": "channel",
			      "channel": "email",
			      "elements": [{ "type": "text", "content": "Welcome aboard, {{name}}." }]
			    }
			  ]
			}`)),
		},
	},
)

NotificationPutContentParams params = NotificationPutContentParams.builder()
    .id("nt_01kx4h2jdafq8bk9aftxak4b40")
    .notificationContentPutRequest(NotificationContentPutRequest.builder()
        .content(NotificationContentPutRequest.Content.builder()
            // The channel builder has no addElement, so its children go in as an additional property.
            .addElement(ElementalChannelNodeWithType.builder()
                .type(ElementalChannelNodeWithType.Type.CHANNEL)
                .channel("email")
                .putAdditionalProperty("elements", JsonValue.from(java.util.List.of(
                    java.util.Map.of("type", "text", "content", "Welcome aboard, {{name}}."))))
                .build())
            .version("2022-01-01")
            .build())
        .build())
    .build();
NotificationContentMutationResponse notificationContentMutationResponse = client.notifications().putContent(params);

$notificationContentMutationResponse = $client->notifications->putContent(
  'nt_01kx4h2jdafq8bk9aftxak4b40',
  content: ['elements' => [['type' => 'channel', 'channel' => 'email', 'elements' => [['type' => 'text', 'content' => 'Welcome aboard, {{name}}.']]]], 'version' => '2022-01-01'],
  state: NotificationTemplateState::DRAFT,
);

NotificationPutContentParams parameters = new()
{
    ID = "nt_01kx4h2jdafq8bk9aftxak4b40",
    Content = new()
    {
        Elements = [new ElementalChannelNodeWithType() { Type = ElementalChannelNodeWithTypeIntersectionMember1Type.Channel }],
        Version = "2022-01-01",
    },
};

var notificationContentMutationResponse = await client.Notifications.PutContent(parameters);

courier notifications put-content \
  --api-key "$COURIER_API_KEY" \
  --id nt_01kx4h2jdafq8bk9aftxak4b40 \
  --content "{elements: [{type: channel, channel: email, elements: [{type: text, content: 'Welcome aboard, {{name}}.'}]}], version: '2022-01-01'}"

With Courier MCP, replace the draft content of my welcome email template with this Elemental document.

Publish

A PUT writes the draft. makes it the active version. You can also publish a historical version to roll back.

await client.notifications.publish('nt_01kx4h2jdafq8bk9aftxak4b40');

client.notifications.publish(
    id="nt_01kx4h2jdafq8bk9aftxak4b40",
)

curl --request POST \
  --url https://api.courier.com/notifications/nt_01kx4h2jdafq8bk9aftxak4b40/publish \
  --header "Authorization: Bearer $COURIER_API_KEY"

result = courier.notifications.publish("nt_01kx4h2jdafq8bk9aftxak4b40")

err := client.Notifications.Publish(
	context.TODO(),
	"nt_01kx4h2jdafq8bk9aftxak4b40",
	courier.NotificationPublishParams{},
)

client.notifications().publish("nt_01kx4h2jdafq8bk9aftxak4b40");

$result = $client->notifications->publish('nt_01kx4h2jdafq8bk9aftxak4b40');

NotificationPublishParams parameters = new() { ID = "nt_01kx4h2jdafq8bk9aftxak4b40" };

await client.Notifications.Publish(parameters);

courier notifications publish \
  --api-key "$COURIER_API_KEY" \
  --id nt_01kx4h2jdafq8bk9aftxak4b40

With Courier MCP, publish my welcome email template.

Aliases

An alias is a name you choose that stands in for a template’s nt_ ID on a send. Your code keeps a readable reference while the template behind it changes. You assign one in the template’s settings, under Alias, not over the API. has the rules and an example.

Read a template’s metrics

returns one template’s sends, deliveries, opens, clicks, errors, and undeliverables over time, broken out per provider and channel. covers the window, granularity, and plan caps.

Preview a template on email clients

renders a template’s email on real clients and returns a screenshot of each. covers device sets, timing, and reading the results.

Approval workflow

If your team gates publishing behind review, enable the approval workflow. Submitting a draft for review happens in the console, which puts the template in a read-only submission state. Over the API you then manage the submission’s checks: read them with , resolve or fail them with PUT, and cancel the submission with DELETE. Creating the submission itself happens in the console.

Manage Templates as code

Export a template to Elemental

is the JSON format Courier uses for template content, so it is what you version-control. Read a template’s content with and commit the { version, elements } JSON to your repo as the source of truth for the template.

Version-control the content

With the Elemental JSON in your repo, review template changes in a pull request like any other code. Apply an approved change back to Courier with . Remove the read-only checksum fields and any locales key that starts with an underscore, and keep each element’s id and locales before you PUT, and see the round-trip contract for the rest.

Manage templates from the CLI

The Courier CLI maps to the same template operations, so you can script create, update, publish, and version listing in CI:

# Create a template from an Elemental file
courier notifications create --api-key "$COURIER_API_KEY" \
  --notification "$(cat welcome-email.json)"

# Update its content from the versioned file
courier notifications put-content --api-key "$COURIER_API_KEY" \
  --id nt_01kx4h2jdafq8bk9aftxak4b40 --content "$(cat welcome-email.content.json)"

# Publish, and list versions to confirm
courier notifications publish --api-key "$COURIER_API_KEY" --id nt_01kx4h2jdafq8bk9aftxak4b40
courier notifications list-versions --api-key "$COURIER_API_KEY" --id nt_01kx4h2jdafq8bk9aftxak4b40

The full verb set is list, create, retrieve, replace, archive, list-versions, publish, duplicate, retrieve-content, put-content, put-element, and put-locale.

Manage templates from an AI agent

The same operations are available as Courier tools (create_notification, put_notification_content, publish_notification, list_notification_versions), so an AI agent can create and update templates in your workspace. Connect the MCP server once and drive template changes from your agent.

Verify the round-trip

Export a template, change a value in the JSON, write it back with put-content, and publish. Confirm the change renders in a test send, then run list-versions and confirm your publish created a new version.

Endpoints

Every operation on a workspace Template. Names and reference links are generated from the OpenAPI spec, so this table can’t drift from what the API serves.

Operation	Method and path
List Templates
Read one
Replace one
Archive one
List versions
Publish
Read content
Replace content
Replace one element
Replace a locale
Read submission checks
Replace submission checks
Cancel a submission
Read metrics

Response codes

Status	Meaning
`200`	The read or write succeeded.
`201`	The Template was created.
`204`	The write succeeded and returned no body.
`400`	The document failed validation. Content stored on a Template needs its top-level elements wrapped in a channel element.
`402`	The workspace’s plan doesn’t include this operation.
`404`	No Template with that id, or no such version.
`409`	The write conflicts with the Template’s current state, such as publishing what is already published.
`429`	Rate limited. Retry after the interval the response names.
`503`	Temporarily unavailable. Retry with backoff.

These come up while working with this API and each is documented once, elsewhere:

Filling variables at send time. Pass data on the send and the Template resolves it. covers the syntax, scope, and the helpers.
Raw HTML for email. covers sending a full HTML document and what a provider does with it.
Workspace against Tenant Templates. These endpoints reach workspace Templates only. A Tenant’s own Templates live under /tenants/{tenant_id}/templates and are documented in .

Verify

Retrieve the template without a version parameter and confirm your published change is live, then send it to a test recipient and confirm it renders in .

Get started

Send messages

Journeys

Broadcasts

Design

Recipients

Tenants

Monitoring

Workspaces

Resources

Manage templates with the API

Prerequisites

Create a template

Content needs a channel to live in

Read a template

Update content: the round-trip contract

Publish

Aliases

Read a template’s metrics

Preview a template on email clients

Approval workflow

Manage Templates as code

Endpoints

Response codes

Verify

​Prerequisites

​Create a template

​Content needs a channel to live in

​Read a template

​Update content: the round-trip contract

​Publish

​Aliases

​Read a template’s metrics

​Preview a template on email clients

​Approval workflow

​Manage Templates as code

​Endpoints

​Response codes

​Where three related things live

​Verify

Prerequisites

Create a template

Content needs a channel to live in

Read a template

Update content: the round-trip contract

Publish

Aliases

Read a template’s metrics

Preview a template on email clients

Approval workflow

Manage Templates as code

Endpoints

Response codes

Where three related things live

Verify