Template translations

A template holds your content once, in your default language, and carries a translation of each piece of it for every language you support. Courier sends each recipient the version in their language.

How it works

You write the template in your default language. Each element (the subject line, a paragraph, a button) gets an id.
You add translations, one locale at a time. Each element stores its translations in a locales map, keyed by a locale code such as es or fr. Get them from your translators or a translation tool such as Lokalise, Crowdin, or Phrase and write them back through the API, or generate them with AI Translation in Design Studio.
Courier picks the translation at send time. It reads the recipient’s locale and swaps in the matching text, element by element. An element with no translation for that locale sends in the default language.

Here’s one element with Spanish and French translations:

{
  "id": "elem_01kx4h2jdafq8bk9b0d2c6yv9p",
  "type": "text",
  "content": "Order {{order_number}} is confirmed.",
  "locales": {
    "es": { "content": "El pedido {{order_number}} está confirmado." },
    "fr": { "content": "La commande {{order_number}} est confirmée." }
  }
}

Each locale stores only the fields it translates, usually the text, so a layout change carries into every language. The same locales map also works on content you pass inline to a send in message.content. Short strings you reuse across many templates, like a common button label, can instead live in your workspace translation strings, one .po file per locale, rendered with {{t}}.

How Courier picks a locale

Courier takes the recipient’s locale from message.to.locale on the send, or from the locale stored on their when the send doesn’t set one. With neither, the default content sends. Locale codes match exactly, including case. A template translated as es serves recipients whose locale is es, and a recipient set to es-MX or ES gets the default content. Design Studio names locales in lowercase, such as es or es-mx, so store the same form on your profiles. Sends use the published template, so translations reach recipients once you publish.

Translate a template with the API

Translating a template through the API takes six steps. The translating itself happens outside Courier, in whatever tool or process you use, and every other step is one call:

Step	Call	Result
1. Create the template		A draft template, with an `id` on every element
2. Export the strings		Each element’s `id`, default text, and `checksum`
3. Translate the strings	None, in your own tool	A translation per element `id`, per locale
4. Write a locale back		One locale’s translations stored on the draft
5. Publish		The translations go live
6. Send it		Each recipient gets their locale

For a template that already exists, start at step 2. When the default text changes later, export again and translate only the strings whose checksum changed.

1. Create the template

takes your default content and returns the template ID as id (nt_01kx4h2jdafq8bk9aftxak4b40 in the later steps). Courier also gives every element an id, which is how translations find their element. You can set your own instead, such as "id": "subject", as long as each one is unique in the template. Elements also accept a locales map here if you already have translations. The brand, subscription, and routing IDs below are placeholders. Set brand and subscription to null if you don’t use them, and set routing.strategy_id to one of your . Content created without a scope field, like this example, reads the send’s data at the root, so the body uses {{order_number}} rather than {{data.order_number}}.

const notificationTemplateResponse = await client.notifications.create({
  notification: {
    name: 'Order Confirmation',
    tags: ['orders'],
    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: 'meta', title: 'Order confirmed' },
            { type: 'text', content: 'Order {{order_number}} is confirmed.' },
            { type: 'action', content: 'View order', href: 'https://app.acme-corp.com/orders' },
          ],
        },
      ],
    },
  },
  state: 'DRAFT',
});

notification_template_response = client.notifications.create(
    notification={
        "name": "Order Confirmation",
        "tags": ["orders"],
        "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": "meta", "title": "Order confirmed"},
                        {"type": "text", "content": "Order {{order_number}} is confirmed."},
                        {"type": "action", "content": "View order", "href": "https://app.acme-corp.com/orders"},
                    ],
                }
            ],
        },
    },
    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": "Order Confirmation",
      "tags": ["orders"],
      "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": "meta", "title": "Order confirmed" },
              { "type": "text", "content": "Order {{order_number}} is confirmed." },
              { "type": "action", "content": "View order", "href": "https://app.acme-corp.com/orders" }
            ]
          }
        ]
      }
    },
    "state": "DRAFT"
  }'

notification_template_response = courier.notifications.create(
  notification: {
    name: "Order Confirmation",
    tags: ["orders"],
    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: "meta", title: "Order confirmed"},
            {type: "text", content: "Order {{order_number}} is confirmed."},
            {type: "action", content: "View order", href: "https://app.acme-corp.com/orders"}
          ]
        }
      ]
    }
  },
  state: "DRAFT"
)

content := param.Override[shared.ElementalContentParam](json.RawMessage(`{
  "version": "2022-01-01",
  "elements": [
    {
      "type": "channel",
      "channel": "email",
      "elements": [
        { "type": "meta", "title": "Order confirmed" },
        { "type": "text", "content": "Order {{order_number}} is confirmed." },
        { "type": "action", "content": "View order", "href": "https://app.acme-corp.com/orders" }
      ]
    }
  ]
}`))

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:    "Order Confirmation",
				Routing: courier.NotificationTemplatePayloadRoutingParam{
					StrategyID: "rs_01kx4h2jdafq8bk9amzvy6hbv0",
				},
				Subscription: courier.NotificationTemplatePayloadSubscriptionParam{
					TopicID: "pt_01kx4h2jdafq8bk9a26x0kvd1t",
				},
				Tags: []string{"orders"},
			},
		},
	},
})

NotificationTemplateCreateRequest params = NotificationTemplateCreateRequest.builder()
    .notification(NotificationTemplateWritePayload.builder()
        .brand(NotificationTemplatePayload.Brand.builder()
            .id("bnd_01kx4mrd0pfzw8wt7pn7p2fzag")
            .build())
        .content(ElementalContent.builder()
            .addElement(ElementalChannelNodeWithType.builder()
                .type(ElementalChannelNodeWithType.Type.CHANNEL)
                .channel("email")
                .putAdditionalProperty("elements", JsonValue.from(java.util.List.of(
                    java.util.Map.of("type", "meta", "title", "Order confirmed"),
                    java.util.Map.of("type", "text", "content", "Order {{order_number}} is confirmed."),
                    java.util.Map.of("type", "action", "content", "View order", "href", "https://app.acme-corp.com/orders"))))
                .build())
            .version("2022-01-01")
            .build())
        .name("Order Confirmation")
        .routing(NotificationTemplatePayload.Routing.builder()
            .strategyId("rs_01kx4h2jdafq8bk9amzvy6hbv0")
            .build())
        .subscription(NotificationTemplatePayload.Subscription.builder()
            .topicId("pt_01kx4h2jdafq8bk9a26x0kvd1t")
            .build())
        .addTag("orders")
        .build())
    .build();
NotificationTemplateResponse notificationTemplateResponse = client.notifications().create(params);

$notificationTemplateResponse = $client->notifications->create(
  notification: [
    'name' => 'Order Confirmation',
    'tags' => ['orders'],
    'brand' => ['id' => 'bnd_01kx4mrd0pfzw8wt7pn7p2fzag'],
    'subscription' => ['topicID' => 'pt_01kx4h2jdafq8bk9a26x0kvd1t'],
    'routing' => ['strategyID' => 'rs_01kx4h2jdafq8bk9amzvy6hbv0'],
    'content' => [
      'version' => '2022-01-01',
      'elements' => [
        [
          'type' => 'channel',
          'channel' => 'email',
          'elements' => [
            ['type' => 'meta', 'title' => 'Order confirmed'],
            ['type' => 'text', 'content' => 'Order {{order_number}} is confirmed.'],
            ['type' => 'action', 'content' => 'View order', 'href' => 'https://app.acme-corp.com/orders'],
          ],
        ],
      ],
    ],
  ],
  state: 'DRAFT',
);

NotificationCreateParams parameters = new()
{
    Notification = new()
    {
        Brand = new("bnd_01kx4mrd0pfzw8wt7pn7p2fzag"),
        Content = new()
        {
            Elements =
            [
                ElementalChannelNodeWithType.FromRawUnchecked(
                    JsonSerializer.Deserialize<Dictionary<string, JsonElement>>("""
                    {
                      "type": "channel",
                      "channel": "email",
                      "elements": [
                        { "type": "meta", "title": "Order confirmed" },
                        { "type": "text", "content": "Order {{order_number}} is confirmed." },
                        { "type": "action", "content": "View order", "href": "https://app.acme-corp.com/orders" }
                      ]
                    }
                    """)),
            ],
            Version = "2022-01-01",
        },
        Name = "Order Confirmation",
        Routing = new("rs_01kx4h2jdafq8bk9amzvy6hbv0"),
        Subscription = new("pt_01kx4h2jdafq8bk9a26x0kvd1t"),
        Tags = ["orders"],
    },
};

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

courier notifications create \
  --api-key "$COURIER_API_KEY" \
  --notification "{name: Order Confirmation, tags: [orders], 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: meta, title: Order confirmed}, {type: text, content: 'Order {{order_number}} is confirmed.'}, {type: action, content: View order, href: 'https://app.acme-corp.com/orders'}]}]}}" \
  --state DRAFT

With Courier MCP, create a draft email template called Order Confirmation with the subject "Order confirmed", the body "Order {{order_number}} is confirmed.", and a View order button linking to https://app.acme-corp.com/orders.

2. Export the strings

returns every element with its id, its default text, a checksum, and any translations already stored. Pass version=draft to read unpublished work. Without it you get the published version, and a template that has never been published returns 404. Templates from the Classic Designer (Legacy) return blocks and channels instead of elements. This workflow is for Elemental templates.

const content = await client.notifications.retrieveContent('nt_01kx4h2jdafq8bk9aftxak4b40', {
  version: 'draft',
});

content = client.notifications.retrieve_content(
    id="nt_01kx4h2jdafq8bk9aftxak4b40",
    version="draft",
)

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

content = courier.notifications.retrieve_content("nt_01kx4h2jdafq8bk9aftxak4b40", version: "draft")

content, err := client.Notifications.GetContent(
	context.TODO(),
	"nt_01kx4h2jdafq8bk9aftxak4b40",
	courier.NotificationGetContentParams{
		Version: courier.String("draft"),
	},
)

var content = client.notifications().retrieveContent(
    NotificationRetrieveContentParams.builder()
        .id("nt_01kx4h2jdafq8bk9aftxak4b40")
        .version("draft")
        .build());

$content = $client->notifications->retrieveContent(
  'nt_01kx4h2jdafq8bk9aftxak4b40',
  version: 'draft',
);

var content = await client.Notifications.RetrieveContent(
    "nt_01kx4h2jdafq8bk9aftxak4b40",
    new() { Version = "draft" }
);

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

With Courier MCP, show me the draft content of template nt_01kx4h2jdafq8bk9aftxak4b40 with its translations.

The response is the template’s element tree, with an id and a checksum on every element:

{
  "version": "2022-01-01",
  "elements": [
    {
      "id": "elem_01kx4h2jdafq8bk9b07z4mq2wd",
      "type": "channel",
      "channel": "email",
      "checksum": "055792c3ddaec6cf26ced79a10394b15",
      "elements": [
        {
          "id": "elem_01kx4h2jdafq8bk9b0a8x3rt5n",
          "type": "meta",
          "title": "Order confirmed",
          "checksum": "ec7fc20765b50a8b3fbacdaf6b4167db"
        },
        {
          "id": "elem_01kx4h2jdafq8bk9b0d2c6yv9p",
          "type": "text",
          "content": "Order {{order_number}} is confirmed.",
          "checksum": "5114903fee322b18acf679bab5de55c1"
        },
        {
          "id": "elem_01kx4h2jdafq8bk9b0g5k7hs1e",
          "type": "action",
          "content": "View order",
          "href": "https://app.acme-corp.com/orders",
          "checksum": "88d1f1c314280c172aaaad3be5311caf"
        }
      ]
    }
  ]
}

Checksums tell you what needs re-translating. An element’s checksum changes when its own content changes, and a container’s changes when anything inside it does. Adding or editing translations leaves it alone, and each translation carries its own checksum inside locales. Store each string’s element id and checksum when you export. On the next export, a changed checksum means new source text to translate, a new id is a new string, and a missing id needs nothing. Export with version=draft each time.

3. Translate the strings

The export is a tree, so walk into every elements array and skip the locales maps. From each element, take its text: title on meta, and content on text, action, quote, and html. Each channel holds its own copy of the content, so a template that sends email and inbox has two of each string. A text element built from inline nodes (bold, links) needs its translation written back as nodes, covered in formatted text. Hand the strings, keyed by element id, to whoever translates them: your own translators, or a translation tool such as Lokalise, Crowdin, or Phrase. Add a note on what each string is so translators have context, and ask them to keep {{variables}} exactly as written. What you send out is a list of strings:

[
  { "id": "elem_01kx4h2jdafq8bk9b0a8x3rt5n", "field": "title", "text": "Order confirmed", "checksum": "ec7fc20765b50a8b3fbacdaf6b4167db", "note": "Email subject" },
  { "id": "elem_01kx4h2jdafq8bk9b0d2c6yv9p", "field": "content", "text": "Order {{order_number}} is confirmed.", "checksum": "5114903fee322b18acf679bab5de55c1", "note": "Email body" },
  { "id": "elem_01kx4h2jdafq8bk9b0g5k7hs1e", "field": "content", "text": "View order", "checksum": "88d1f1c314280c172aaaad3be5311caf", "note": "Button label" }
]

What comes back is the same list with the translation for each locale:

[
  { "id": "elem_01kx4h2jdafq8bk9b0a8x3rt5n", "field": "title", "es": "Pedido confirmado" },
  { "id": "elem_01kx4h2jdafq8bk9b0d2c6yv9p", "field": "content", "es": "El pedido {{order_number}} está confirmado." },
  { "id": "elem_01kx4h2jdafq8bk9b0g5k7hs1e", "field": "content", "es": "Ver pedido" }
]

The file format is up to you and your tool. Courier only needs each translation matched to its element id and field in the next step.

4. Write a locale back

sets one locale’s translations. Turn what came back into one request per locale: each entry names an element by id and carries its translated fields. Add any localized links yourself, like the Spanish href for the button below. The fields an element accepts depend on its type (see which fields a locale can override).

await client.notifications.putLocale('es', {
  id: 'nt_01kx4h2jdafq8bk9aftxak4b40',
  elements: [
    { id: 'elem_01kx4h2jdafq8bk9b0a8x3rt5n', title: 'Pedido confirmado' },
    { id: 'elem_01kx4h2jdafq8bk9b0d2c6yv9p', content: 'El pedido {{order_number}} está confirmado.' },
    { id: 'elem_01kx4h2jdafq8bk9b0g5k7hs1e', content: 'Ver pedido', href: 'https://app.acme-corp.com/es/orders' },
  ],
});

client.notifications.put_locale(
    locale_id="es",
    id="nt_01kx4h2jdafq8bk9aftxak4b40",
    elements=[
        {"id": "elem_01kx4h2jdafq8bk9b0a8x3rt5n", "title": "Pedido confirmado"},
        {"id": "elem_01kx4h2jdafq8bk9b0d2c6yv9p", "content": "El pedido {{order_number}} está confirmado."},
        {"id": "elem_01kx4h2jdafq8bk9b0g5k7hs1e", "content": "Ver pedido", "href": "https://app.acme-corp.com/es/orders"},
    ],
)

curl --request PUT \
  --url https://api.courier.com/notifications/nt_01kx4h2jdafq8bk9aftxak4b40/locales/es \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "elements": [
      { "id": "elem_01kx4h2jdafq8bk9b0a8x3rt5n", "title": "Pedido confirmado" },
      { "id": "elem_01kx4h2jdafq8bk9b0d2c6yv9p", "content": "El pedido {{order_number}} está confirmado." },
      { "id": "elem_01kx4h2jdafq8bk9b0g5k7hs1e", "content": "Ver pedido", "href": "https://app.acme-corp.com/es/orders" }
    ]
  }'

courier.notifications.put_locale(
  "es",
  id: "nt_01kx4h2jdafq8bk9aftxak4b40",
  elements: [
    {id: "elem_01kx4h2jdafq8bk9b0a8x3rt5n", title: "Pedido confirmado"},
    {id: "elem_01kx4h2jdafq8bk9b0d2c6yv9p", content: "El pedido {{order_number}} está confirmado."},
    {id: "elem_01kx4h2jdafq8bk9b0g5k7hs1e", content: "Ver pedido", href: "https://app.acme-corp.com/es/orders"}
  ]
)

_, err := client.Notifications.PutLocale(
	context.TODO(),
	"es",
	courier.NotificationPutLocaleParams{
		ID: "nt_01kx4h2jdafq8bk9aftxak4b40",
		NotificationLocalePutRequest: courier.NotificationLocalePutRequestParam{
			// Translated fields vary by element type, so they go in ExtraFields.
			Elements: []courier.NotificationLocalePutRequestElementParam{
				{ID: "elem_01kx4h2jdafq8bk9b0a8x3rt5n", ExtraFields: map[string]any{"title": "Pedido confirmado"}},
				{ID: "elem_01kx4h2jdafq8bk9b0d2c6yv9p", ExtraFields: map[string]any{"content": "El pedido {{order_number}} está confirmado."}},
				{ID: "elem_01kx4h2jdafq8bk9b0g5k7hs1e", ExtraFields: map[string]any{"content": "Ver pedido", "href": "https://app.acme-corp.com/es/orders"}},
			},
		},
	},
)

// Translated fields vary by element type, so they go in as additional properties.
NotificationPutLocaleParams params = NotificationPutLocaleParams.builder()
    .id("nt_01kx4h2jdafq8bk9aftxak4b40")
    .localeId("es")
    .notificationLocalePutRequest(NotificationLocalePutRequest.builder()
        .addElement(NotificationLocalePutRequest.Element.builder()
            .id("elem_01kx4h2jdafq8bk9b0a8x3rt5n")
            .putAdditionalProperty("title", JsonValue.from("Pedido confirmado"))
            .build())
        .addElement(NotificationLocalePutRequest.Element.builder()
            .id("elem_01kx4h2jdafq8bk9b0d2c6yv9p")
            .putAdditionalProperty("content", JsonValue.from("El pedido {{order_number}} está confirmado."))
            .build())
        .addElement(NotificationLocalePutRequest.Element.builder()
            .id("elem_01kx4h2jdafq8bk9b0g5k7hs1e")
            .putAdditionalProperty("content", JsonValue.from("Ver pedido"))
            .putAdditionalProperty("href", JsonValue.from("https://app.acme-corp.com/es/orders"))
            .build())
        .build())
    .build();
client.notifications().putLocale(params);

$client->notifications->putLocale(
  'es',
  id: 'nt_01kx4h2jdafq8bk9aftxak4b40',
  elements: [
    ['id' => 'elem_01kx4h2jdafq8bk9b0a8x3rt5n', 'title' => 'Pedido confirmado'],
    ['id' => 'elem_01kx4h2jdafq8bk9b0d2c6yv9p', 'content' => 'El pedido {{order_number}} está confirmado.'],
    ['id' => 'elem_01kx4h2jdafq8bk9b0g5k7hs1e', 'content' => 'Ver pedido', 'href' => 'https://app.acme-corp.com/es/orders'],
  ],
);

// Translated fields vary by element type, so each entry is built from raw JSON.
static Element Entry(string json) =>
    Element.FromRawUnchecked(JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(json)!);

await client.Notifications.PutLocale(
    "es",
    new()
    {
        ID = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Elements =
        [
            Entry("""{ "id": "elem_01kx4h2jdafq8bk9b0a8x3rt5n", "title": "Pedido confirmado" }"""),
            Entry("""{ "id": "elem_01kx4h2jdafq8bk9b0d2c6yv9p", "content": "El pedido {{order_number}} está confirmado." }"""),
            Entry("""{ "id": "elem_01kx4h2jdafq8bk9b0g5k7hs1e", "content": "Ver pedido", "href": "https://app.acme-corp.com/es/orders" }"""),
        ],
    }
);

courier notifications put-locale \
  --api-key "$COURIER_API_KEY" \
  --id nt_01kx4h2jdafq8bk9aftxak4b40 \
  --locale-id es \
  --element "{id: elem_01kx4h2jdafq8bk9b0a8x3rt5n, title: Pedido confirmado}" \
  --element "{id: elem_01kx4h2jdafq8bk9b0d2c6yv9p, content: 'El pedido {{order_number}} está confirmado.'}" \
  --element "{id: elem_01kx4h2jdafq8bk9b0g5k7hs1e, content: Ver pedido, href: 'https://app.acme-corp.com/es/orders'}"

With Courier MCP, add a Spanish (es) translation to template nt_01kx4h2jdafq8bk9aftxak4b40: subject "Pedido confirmado", body "El pedido {{order_number}} está confirmado.", and a "Ver pedido" button linking to https://app.acme-corp.com/es/orders.

The write merges into what’s there. It touches only the locale in the path and only the elements you list, so your default content and every other language stay as they are. Within an element, each field you send replaces that field’s translation and the fields you leave out keep theirs. That means you can send a translation tool’s changes for a handful of strings without re-sending the rest. Leave untranslated strings out, and they send in the default language. Every id must exist in the template. An unknown id returns a 400 that lists each one, and nothing is written.

5. Publish

Writes land on the draft by default. Publish with once the translations are in, or pass "state": "PUBLISHED" on the locale write to publish in the same call. Publishing releases everything on the draft, including edits other than yours.

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"

courier.notifications.publish("nt_01kx4h2jdafq8bk9aftxak4b40")

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

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

$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 template nt_01kx4h2jdafq8bk9aftxak4b40.

6. Send it

Send the template as usual. Set locale on the recipient, or store it on their profile so every send picks it up.

const { requestId } = await client.send.message({
  message: {
    to: { user_id: 'user_123', locale: 'es' },
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
    data: { order_number: '1042' },
  },
});

response = client.send.message(
    message={
        "to": {"user_id": "user_123", "locale": "es"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "data": {"order_number": "1042"},
    }
)

curl --request POST \
  --url https://api.courier.com/send \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "message": {
      "to": { "user_id": "user_123", "locale": "es" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "data": { "order_number": "1042" }
    }
  }'

response = courier.send_.message(
  message: {
    to: {user_id: "user_123", locale: "es"},
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: {order_number: "1042"}
  }
)

response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{
				UserID: courier.String("user_123"),
				Locale: courier.String("es"),
			},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Data:     map[string]any{"order_number": "1042"},
	},
})

SendMessageResponse response = client.send().message(SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder()
            .userId("user_123")
            .locale("es")
            .build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(SendMessageParams.Message.Data.builder()
            .putAdditionalProperty("order_number", JsonValue.from("1042"))
            .build())
        .build())
    .build());

$response = $client->send->message(
  message: [
    'to' => ['userID' => 'user_123', 'locale' => 'es'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'data' => ['order_number' => '1042'],
  ],
);

var response = await client.Send.Message(new SendMessageParams
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123", Locale = "es" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "order_number", JsonSerializer.SerializeToElement("1042") },
        },
    },
});

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123", "locale": "es"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.data '{"order_number": "1042"}'

With Courier MCP, set the locale on user_123's profile to es, then send template nt_01kx4h2jdafq8bk9aftxak4b40 to user_123 with order number 1042.

user_123 gets “Pedido confirmado” with the Spanish body and button. Check the rendered message in or with .

Translate in Design Studio

translates a template for you. Open the template, select the globe icon, and add a language. With Translate with AI checked, which is the default, Courier translates every string, including subject lines, headings, body copy, and button text. Review the result in a two-column view, with the default on the left and the translation on the right, and edit any string. When you change the default content, Courier marks translations that may be out of date, and you can re-translate them one at a time or all together. Publish the template to send the translations. AI Translation runs on AI credits, which you can buy on the Business or Enterprise plan. Each translation request costs 2.5 credits plus token overages, from the same balance as . A long template can take more than one request per locale. Translations made in Design Studio and through the API are the same locales data, so you can use both on one template.

Other ways to write translations

Replace all content. writes the whole element tree, translations included. Read the draft with version=draft, remove every checksum (on elements and inside locales), and keep each element’s id and locales. Templates translated in Design Studio also carry keys starting with an underscore, such as _sourceHash, inside locales. Remove those too, because the write rejects them. An element sent without an id gets a new one, and content sent without locales has no translations.
Replace one element. replaces a single element, so include its locales in the body to keep them. For translation work, the locale endpoint above is the better fit.
Remove a locale. The locale endpoint adds and updates. To remove a language, read the draft, delete that code from each element’s locales, and write the content back with as above.
Journey templates. A template that belongs to a journey has the same calls under the journey, with the same bodies: to export, to write a locale, and to publish.

Which fields a locale can override

The fields a locale entry accepts depend on the element type:

Field	Element types	Use it for
`content`	`text`, `action`, `quote`, `html`	Body copy and button labels
`title`	`meta`	Email subject lines and push titles
`href`	`action`, `image`	Language-specific links
`src`	`image`	Images with text baked in
`raw`	`channel`	Provider-native overrides, such as a translated `subject` or a whole translated `html` body
`elements`	`text` (inline nodes); `list-item` (inline nodes or a nested list); `channel`, `group`, `column` (full nodes); `columns` (column nodes); `list` (list-item nodes)	Nested content, such as formatted text

divider, jsonnet, partial, and comment elements take no locale entry. A field the element type doesn’t accept returns a 400 naming it. Sending elements or raw in a locale replaces that field’s whole value for the element, so include everything each time.

Formatted text

A text element can hold its copy as a content string or as an elements array of inline nodes (string, link, img). Give a formatted element its translations as elements too, so bold, italic, and links carry into every language:

{
  "type": "text",
  "elements": [
    { "type": "string", "content": "Your order " },
    { "type": "string", "content": "#{{order_number}}", "bold": true },
    { "type": "string", "content": " is " },
    { "type": "string", "content": "confirmed", "bold": true },
    { "type": "string", "content": "." }
  ],
  "locales": {
    "fr": {
      "elements": [
        { "type": "string", "content": "Votre commande " },
        { "type": "string", "content": "#{{order_number}}", "bold": true },
        { "type": "string", "content": " est " },
        { "type": "string", "content": "confirmée", "bold": true },
        { "type": "string", "content": "." }
      ]
    },
    "es": {
      "content": "Tu pedido #{{order_number}} está confirmado."
    }
  }
}

Text node resolution

A locale can use either format. Courier uses the locale field that matches the element’s own format, and falls back to the other:

Element has	Locale provides	Renders
`elements`	`elements`, with or without `content`	The locale’s array
`elements`	`content` only	The locale’s string as a single plain node, without the original formatting
`content` only	`content`, with or without `elements`	The locale’s string
`content` only	`elements` only	The locale’s array

Workspace translation strings

Workspace translations hold short strings reused across templates, like button labels and common phrases. They’re keyed by locale and rendered with the {{t}} Handlebars helper. Manage them with and reference a string with {{t "welcome_headline"}}. Use this for a shared glossary, and per-locale template content for the body of a notification.

The payload is a .po file, the gettext format most translation tools already export. Send the file as the raw request body with Content-Type: text/plain.
domain is always default. Any other value returns a 400.
Read them back with , which returns the stored .po content, to compare what’s live with what your translation system holds.

Upload a locale’s file like this:

curl --request PUT \
  --url https://api.courier.com/translations/default/es \
  --header "Authorization: Bearer $COURIER_API_KEY" \
  --header "Content-Type: text/plain" \
  --data-binary @es.po

{{t}} renders from the recipient’s locale. A send renders a {{t}} string only when the recipient has a locale with an uploaded .po file. With no locale, or a locale that has no file, the message fails with translate helper: Could not find translations. A key missing from an uploaded file renders as the key itself. Translations are per workspace. A customer who needs different wording from a needs a different template.

Manage templates with the API

Create, read, update, and publish templates.

Elemental

The content format every element and locale lives in.

Get started

Send messages

Journeys

Broadcasts

Design

Recipients

Tenants

Monitoring

Workspaces

Resources

Template translations

How it works

How Courier picks a locale

Translate a template with the API

1. Create the template

2. Export the strings

3. Translate the strings

4. Write a locale back

5. Publish

6. Send it

Translate in Design Studio

Other ways to write translations

Which fields a locale can override

Formatted text

Text node resolution

Workspace translation strings

Manage templates with the API

Elemental

​How it works

​How Courier picks a locale

​Translate a template with the API

​1. Create the template

​2. Export the strings

​3. Translate the strings

​4. Write a locale back

​5. Publish

​6. Send it

​Translate in Design Studio

​Other ways to write translations

​Which fields a locale can override

​Formatted text

​Text node resolution

​Workspace translation strings

​Related docs

Manage templates with the API

Elemental

How it works

How Courier picks a locale

Translate a template with the API

1. Create the template

2. Export the strings

3. Translate the strings

4. Write a locale back

5. Publish

6. Send it

Translate in Design Studio

Other ways to write translations

Which fields a locale can override

Formatted text

Text node resolution

Workspace translation strings

Related docs