Localize notifications with the API

The localization API is a two-step flow: fetch your template’s translatable content, then update it with locale-specific strings. Courier stores translations at the block and channel level, so you can sync from a script, CI/CD pipeline, or translation management system. This tutorial walks through both steps using a welcome email (nt_01ABC) translated to French. For sending with locales, TMS webhooks, and the full endpoint reference, see Localization.

Fetch translatable content

Call GET /notifications/{id}/content to get every field you can translate:

curl -X GET "https://api.courier.com/notifications/nt_01ABC/content" \
  -H "Authorization: Bearer $COURIER_API_KEY"

const { blocks, channels } = await fetch(
  "https://api.courier.com/notifications/nt_01ABC/content",
  { headers: { Authorization: `Bearer ${apiKey}` } }
).then((r) => r.json());

The response has two arrays:

Field	What it contains
`blocks`	Body content: text, buttons, lists. Each item has an `id`, default `content`, existing `locales`, and a `checksum`.
`channels`	Channel-level content: email subjects, push titles. Each item has an `id`, default `content`, and existing `locales`.

{
  "blocks": [{
    "id": "block_43c114d9-9cfd-4340-808f-17e2fc7a4c87",
    "type": "text",
    "content": "Hello <variable id=\"3\">{name}</variable>, welcome to Courier!",
    "checksum": "fb60f2098fa407a4ff8d48e3e908d889",
    "locales": {}
  }],
  "channels": [{
    "id": "channel_456",
    "type": "email",
    "content": { "subject": "Welcome!" },
    "locales": {}
  }]
}

Save the id from each block and channel. You’ll pass them to the update endpoints. Use checksum to detect when default content changed and a translation needs re-syncing.

Update translations

Pick the endpoint that matches how much you’re updating:

One block

POST /notifications/{id}/blocks/{block_id}/locales Use this when syncing a single string from your database or TMS.

curl -X POST "https://api.courier.com/notifications/nt_01ABC/blocks/block_43c114d9/locales" \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fr_FR": "Bonjour <variable id=\"3\">{name}</variable>, bienvenue sur Courier !"}'

One channel

POST /notifications/{id}/channels/{channel_id}/locales Use this for email subjects or push titles. Pass a plain string per locale:

curl -X POST "https://api.courier.com/notifications/nt_01ABC/channels/channel_456/locales" \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fr_FR": "Bienvenue !"}'

All blocks and channels

PUT /notifications/{id}/locales Use this for CI/CD jobs or full template syncs. Include every block and channel in one request. Channel values use an object ({ "subject": "..." } for email, { "title": "..." } for push):

curl -X PUT "https://api.courier.com/notifications/nt_01ABC/locales" \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "blocks": [{
      "id": "block_43c114d9-9cfd-4340-808f-17e2fc7a4c87",
      "type": "text",
      "locales": {
        "fr_FR": "Bonjour <variable id=\"3\">{name}</variable>, bienvenue sur Courier !"
      }
    }],
    "channels": [{
      "id": "channel_456",
      "locales": { "fr_FR": { "subject": "Bienvenue !" } }
    }]
  }'

One locale, all fields

PUT /notifications/{id}/locales/{locale} Same as bulk, but scoped to a single language. Use this when you’re adding French without touching existing German translations. All update endpoints return 204 No Content on success.

Preserve <variable> tags and their original id values in translated strings. Courier uses these for variable substitution.

For list blocks, pass an object with parent and children keys instead of a plain string. See Localization for all block formats.

Draft vs published paths

Every endpoint is available at two paths:

Path	Behavior
`/notifications/{id}/...`	Updates the published template. Changes are live immediately.
`/notifications/{id}/draft/...`	Updates the draft. Requires a publish step before changes go live.

Use the published paths for scripts and CI/CD. Use draft paths when you need a review step or TMS approval workflow. To publish draft changes:

curl -X POST "https://api.courier.com/notifications/nt_01ABC/publish" \
  -H "Authorization: Bearer $COURIER_API_KEY"

Send Messages

Design Messages

User Journeys

Inbox & Preferences

Deploying and Debugging

Migrate to Courier

Localize notifications with the API

Fetch translatable content

Update translations

One block

One channel

All blocks and channels

One locale, all fields

Draft vs published paths

What’s next

Translate with AI

Localization reference

​Fetch translatable content

​Update translations

​One block

​One channel

​All blocks and channels

​One locale, all fields

​Draft vs published paths

​What’s next

Translate with AI

Localization reference

Fetch translatable content

Update translations

One block

One channel

All blocks and channels

One locale, all fields

Draft vs published paths

What’s next