> ## Documentation Index
> Fetch the complete documentation index at: https://www.courier.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Install the Courier skill before writing code: `npx skills add trycourier/courier-skills`. It carries the verified SDK shapes and the rules you cannot get wrong.
> Authenticate every request with `Authorization: Bearer <API_KEY>`. A workspace has several environments and each has its own keys, which are plain `pk_` strings with no environment prefix. Start with Test.
> Send with `client.send.message` from the Node SDK (`@trycourier/courier` v7 and later, where the client is the default import). Reference a template by its `nt_` id or its alias.
> A send accepts a bare Elemental element list, but storing content on a template requires the top-level elements wrapped in a channel element.
> To translate a template, write one locale at a time with `PUT /notifications/{id}/locales/{localeId}`, which merges into the existing translations. `PUT /notifications/{id}/content` and `PUT /notifications/{id}/elements/{elementId}` overwrite translations along with the content, so send each element's `id` and `locales` back, and first remove every `checksum` and any `locales` key that starts with an underscore.
> Templates and journeys can be built in the Courier app or created through the API. Either way they live in the workspace and are referenced by ID when you send.
> The hosted MCP server is https://mcp.courier.com. For a briefing on what Courier is and when to use it, read https://www.courier.com/llms.txt.
> Prefer the Guides tab for how-do-I questions and the Docs tab for how-does-it-behave questions. The API reference lives under /api-reference.

# Message routing and failover

> How Courier picks the channels and providers for each message, falls back when one can't deliver, and where you set routing: a strategy or the send.

Routing decides which channels a message goes out on and which provider delivers each one. When an option can't deliver, Courier moves to the next, so a user without a push token still gets the email.

## Two decisions: channel, then provider

Courier routes every message in two steps. It picks channels from the routing object's `channels` list, then picks providers inside each channel in priority order. Each step has its own method:

| Decision | Set with | `single` | `all` |
| :- | :- | :- | :- |
| Which channels | `routing.method` | Tries channels in order and stops at the first that delivers | Sends on every channel in the list |
| Which providers | The channel's `routing_method` | Tries providers in order and stops at the first that delivers (the default) | Sends through every provider on the channel |

Failover happens at both levels. Under `single`, everything after the first option is its backup.

## Where routing is set

Most templates carry their routing in a routing strategy: a saved set of channels, fallback order, and providers, attached to the template by ID. Build one in Design Studio or with the API, and every template that uses it picks up your edits on its next send. See [Routing strategies](https://www.courier.com/docs/send/routing-strategies.md).

To change routing for one message, pass a `routing` object on the send:

```javascript Node.js highlight={5-8} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    routing: {
      method: "single",
      channels: ["apn", "firebase-fcm", "email"],
    },
  },
});
```

```python Python highlight={5-8} theme={null}
response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "routing": {
            "method": "single",
            "channels": ["apn", "firebase-fcm", "email"],
        },
    },
)
```

```bash cURL highlight={8-11} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "routing": {
        "method": "single",
        "channels": ["apn", "firebase-fcm", "email"]
      }
    }
  }'
```

```ruby Ruby highlight={5-8} theme={null}
response = courier.send_.message(
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    routing: {
      method: "single",
      channels: ["apn", "firebase-fcm", "email"]
    }
  }
)
```

```go Go highlight={7-14} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{UserID: courier.String("user_123")},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Routing: courier.SendMessageParamsMessageRouting{
			Method: string(shared.MessageRoutingMethodSingle),
			Channels: []shared.MessageRoutingChannelUnionParam{
				{OfString: courier.String("apn")},
				{OfString: courier.String("firebase-fcm")},
				{OfString: courier.String("email")},
			},
		},
	},
})
```

```java Java highlight={5-10} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .routing(SendMessageParams.Message.Routing.builder()
            .method(SendMessageParams.Message.Routing.Method.SINGLE)
            .addChannel("apn")
            .addChannel("firebase-fcm")
            .addChannel("email")
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={5-8} theme={null}
$response = $client->send->message(
  message: [
    'to' => ['user_id' => 'user_123'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'routing' => [
      'method' => 'single',
      'channels' => ['apn', 'firebase-fcm', 'email'],
    ],
  ],
);
```

```csharp C# highlight={4-8} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Routing = new Routing { Method = Method.Single, Channels = ["apn", "firebase-fcm", "email"] },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={5} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.routing '{"method": "single", "channels": ["apn", "firebase-fcm", "email"]}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123, trying push through APNs and FCM first and falling back to email.
```

An inline `routing` object replaces the strategy's channel list and method for that message. The strategy's provider order and channel conditions still apply to the channels you list. With neither, Courier uses the workspace's default routing, which is `{ "method": "single", "channels": ["email"] }` unless your workspace has saved its own.

The recipient's [preferences](https://www.courier.com/docs/recipients/preferences/overview.md) apply on top of routing. An opted-out topic blocks the send, and a user who picked their own channels for a topic gets those channels instead.

## Common patterns

Each pattern is a `routing` object. Pass it on a send, or save the same shape as a strategy.

### Fall back to another channel

Courier tries push through APNs, then FCM, then email, then SMS, and stops at the first that delivers. A user with no push token gets the email, and SMS goes out only if email fails too:

```json theme={null}
{ "method": "single", "channels": ["apn", "firebase-fcm", "email", "sms"] }
```

**Name push providers, not the `push` channel, when Inbox is installed.** Courier Inbox answers the `push` channel too, so `["push", "email"]` delivers to Inbox and stops there, and the email never goes out. List the push providers you use by their provider key, such as `apn` and `firebase-fcm`.

### Send on every channel

Email and Inbox both go out. Each channel fails over among its own providers, so a failed email doesn't stop the Inbox message:

```json theme={null}
{ "method": "all", "channels": ["email", "inbox"] }
```

### Always send one channel, fall back across the rest

An entry in `channels` can be a nested routing object with its own `method`. Here the Inbox message always goes out, and the user also gets push, or email if push can't deliver:

```json theme={null}
{
  "method": "all",
  "channels": [
    "inbox",
    { "method": "single", "channels": ["apn", "firebase-fcm", "email"] }
  ]
}
```

Design Studio's **Advanced** routing scheme saves this shape.

### Reach every device on push

APNs and FCM are two providers inside the one `push` channel, and a channel's `routing_method` defaults to `single`. Courier delivers through the first provider that works and stops, so a user with both an iPhone and an Android tablet gets the notification on one device.

Set the push channel's `routing_method` to `all`, and list its `providers` so Courier Inbox, also a push provider, doesn't get a copy. Both go in `message.channels`, keyed by channel name, not in the `routing` object:

```javascript Node.js highlight={7} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    routing: { method: "single", channels: ["push"] },
    channels: {
      push: { routing_method: "all", providers: ["apn", "firebase-fcm"] },
    },
  },
});
```

```python Python highlight={7} theme={null}
response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "routing": {"method": "single", "channels": ["push"]},
        "channels": {
            "push": {"routing_method": "all", "providers": ["apn", "firebase-fcm"]},
        },
    },
)
```

```bash cURL highlight={10} theme={null}
curl -X POST https://api.courier.com/send \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "to": { "user_id": "user_123" },
      "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
      "routing": { "method": "single", "channels": ["push"] },
      "channels": {
        "push": { "routing_method": "all", "providers": ["apn", "firebase-fcm"] }
      }
    }
  }'
```

```ruby Ruby highlight={7} theme={null}
response = courier.send_.message(
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    routing: { method: "single", channels: ["push"] },
    channels: {
      push: { routing_method: "all", providers: ["apn", "firebase-fcm"] }
    }
  }
)
```

```go Go highlight={13} theme={null}
response, err := client.Send.Message(context.TODO(), courier.SendMessageParams{
	Message: courier.SendMessageParamsMessage{
		To: courier.SendMessageParamsMessageToUnion{
			OfUserRecipient: &shared.UserRecipientParam{UserID: courier.String("user_123")},
		},
		Template: courier.String("nt_01kx4h2jdafq8bk9aftxak4b40"),
		Routing: courier.SendMessageParamsMessageRouting{
			Method:   string(shared.MessageRoutingMethodSingle),
			Channels: []shared.MessageRoutingChannelUnionParam{{OfString: courier.String("push")}},
		},
		Channels: shared.MessageChannelsParam{
			"push": shared.ChannelParam{
				RoutingMethod: shared.ChannelRoutingMethodAll,
				Providers:     []string{"apn", "firebase-fcm"},
			},
		},
	},
})
```

```java Java highlight={11} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .routing(SendMessageParams.Message.Routing.builder()
            .method(SendMessageParams.Message.Routing.Method.SINGLE)
            .addChannel("push")
            .build())
        .channels(MessageChannels.builder()
            .putAdditionalProperty("push", JsonValue.from(java.util.Map.of(
                "routing_method", "all",
                "providers", java.util.List.of("apn", "firebase-fcm"))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={7} theme={null}
$response = $client->send->message(
  message: [
    'to' => ['user_id' => 'user_123'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'routing' => ['method' => 'single', 'channels' => ['push']],
    'channels' => [
      'push' => ['routing_method' => 'all', 'providers' => ['apn', 'firebase-fcm']],
    ],
  ],
);
```

```csharp C# highlight={10} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Routing = new Routing { Method = Method.Single, Channels = ["push"] },
        Channels = new Dictionary<string, Channel>()
        {
            { "push", new() { RoutingMethod = RoutingMethod.All, Providers = ["apn", "firebase-fcm"] } },
        },
    },
};

var response = await client.Send.Message(parameters);
```

```bash CLI highlight={6} theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.routing '{"method": "single", "channels": ["push"]}' \
  --message.channels '{"push": {"routing_method": "all", "providers": ["apn", "firebase-fcm"]}}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 on push through APNs and FCM only, reaching every device rather than stopping at the first.
```

A user with only an iPhone gets the same result either way, because Courier skips FCM when the user has no FCM token.

Routing `{ "method": "all", "channels": ["apn", "firebase-fcm"] }` does the same without the `channels` override.

> [!NOTE]
>
> **Both providers have to be installed.**\\
>
> `routing_method` decides how many of the push channel's providers Courier uses. Install APNs and Firebase FCM under [Integrations](https://app.courier.com/integrations), and Courier includes both.

### Send through one provider

Put a provider key such as `twilio` in `channels` instead of a channel name, and Courier sends through that provider alone. See [Send to a provider](https://www.courier.com/docs/send/send-to-a-provider.md).

## Channel priority

Inside a channel, Courier tries providers in this order:

1. The providers listed for that channel in the strategy, in the order you set.
2. Any other provider you've configured for the channel.

Courier skips a provider that can't reach the recipient, such as an SMS provider for a user with no `phone_number`, or whose `if` condition is false. A condition on the channel skips the whole channel. [Channel overrides](https://www.courier.com/docs/send/overrides.md) covers writing conditions.

To change the provider order for one send, list the providers in `message.channels`:

```json theme={null}
{
  "channels": {
    "email": { "providers": ["ses", "sendgrid"] }
  }
}
```

## Failover

Courier moves to the next provider in a channel when one can't take the message or returns an error. It retries transient errors, such as a rate limit or a dropped connection, before moving on. A channel fails when every provider on it has failed or the recipient has no address for it, and a `single` route then moves to the next channel. If every option in the route fails, the message fails.

Every attempt shows in the message's [log](https://www.courier.com/docs/monitor/logs.md).

Failover acts on errors at send time. A bounce is reported after the provider accepts the email, so it never triggers failover. To send an SMS when an email bounces, or an email when a push isn't delivered, see [Fall back when a message isn't delivered](https://www.courier.com/docs/guides/fall-back-when-undelivered.md).

## Timeouts

Courier retries provider errors for about 24 hours, roughly 104 attempts. `message.timeout.message` sets the message's overall timeout in milliseconds. It defaults to 72 hours, which is also the cap. A shorter timeout ends retries sooner.

On an Enterprise plan, Courier also moves past a slow provider or channel. It gives each provider 5 minutes and each channel 30 minutes, and you can change both per send. On other plans, a send that sets channel or provider timeouts returns `402`.

## FAQ

> [accordion] What is the difference between single and all?
>
> `single` sends through the first channel that delivers and keeps the rest as failover. `all` sends through every channel in the list at once. A channel's own `routing_method` makes the same choice between the providers inside it.

> [accordion] Does a routing object on the send replace the template's routing strategy?
>
> An inline `routing` object replaces the strategy's channel list and method for that one message. The strategy's provider order and channel conditions still apply, so you can reorder channels on a send without losing the rest of the configuration.

> [accordion] How do I send one push to both iOS and Android?
>
> Set the push channel's `routing_method` to `all` in `message.channels`, and install both APNs and Firebase FCM under Integrations. See [reach every device on push](#reach-every-device-on-push).

> [accordion] Is failover available on every plan?
>
> Failover on errors works on every plan: Courier moves to the next provider or channel when one can't deliver. Moving past a provider or channel that is slow, rather than failed, requires an Enterprise plan.
