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

# Channel settings and overrides

> Set a template's email fields and channel conditions, and override channel or provider payloads on one send without editing the template.

Channel settings control how each channel behaves within a template, and send-time overrides let you adjust a single message.

## How overrides work

An override changes part of a message at send time, without editing the template. Courier applies it just before handing the message to the provider, so it works with template-based sends and with any [Elemental](https://www.courier.com/docs/design/elemental/overview.md) content the template renders.

There are two levels:

| Level | Where you set it | Applies to |
| :- | :- | :- |
| **Channel override** | `message.channels.<channel>.override` | Every provider configured for that channel |
| **Provider override** | `message.providers.<key>.override` | One provider, passing fields from that provider's own API |

Use both on the same send if you need to. When the two set the same field, **the provider override wins**.

> [!NOTE]
>
> Courier applies overrides **after** the render step. The Rendered tab in the logs won't show them, only the pre-override output. To see the final payload, look at the provider request in the Raw tab.

The fields each channel accepts live with that channel: [email](https://www.courier.com/docs/integrations/email/overview.md#channel-overrides), [SMS](https://www.courier.com/docs/integrations/sms/overview.md#channel-overrides), [push](https://www.courier.com/docs/integrations/push/overview.md#channel-overrides), and [chat](https://www.courier.com/docs/integrations/direct-message/overview.md#channel-overrides). Each provider page documents its own provider-specific schema.

## Prerequisites

* A template with more than one channel
* A connected provider for each of those channels

## Configure channels

**1. Set email address fields**

Email channels carry sender and recipient fields you set in the channel settings, with variables allowed for dynamic values:

* **From**: `"Sarah Bennett <notify@acme-corp.com>"`. The `Name <email>` form carries the display name, and it is the only way to set one when a provider's integration has no From Name field.
* **Reply-To**: where replies go.
* **CC / BCC**: additional recipients, often driven by a variable.

The sender resolves at three levels, and the first one set wins:

1. `message.channels.email.override.from` on the send, for one message.
2. The **From** field here, for every send of this template.
3. **From Address** on the provider integration, for every email through that provider.

With none of the three set, the send fails at the provider rather than falling back to a Courier address. [Send from your own domain](https://www.courier.com/docs/guides/send-from-your-domain.md) walks the whole setup.

> [!NOTE]
>
> Gmail is the exception. It always sends as the authorized inbox, so a **From** value here has no effect on it. Set the display name with the integration's From Name instead.

**2. Add per-channel conditions**

A channel condition skips only that channel, while the rest of the notification still delivers (a template condition, by contrast, stops the whole send). In the console, a routing strategy's channel **Conditions** tab sets one for every template that uses that strategy. On a single send, use `message.channels.<channel>.if`, where each value is an expression evaluated against `data` and `profile`:

```javascript Node.js highlight={9} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    channels: {
      sms: {
        if: "data.priority === 'high'",
      },
    },
  },
});
```

```python Python highlight={9} theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "channels": {
            "sms": {
                "if": "data.priority === 'high'",
            },
        },
    },
)
```

```bash cURL highlight={12} wrap 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",
      "channels": {
        "sms": {
          "if": "data.priority === '\''high'\''"
        }
      }
    }
  }'
```

```ruby Ruby highlight={9} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    channels: {
      sms: {
        if: "data.priority === 'high'"
      }
    }
  }
)
```

```go Go highlight={10} 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"),
		Channels: shared.MessageChannelsParam{
			"sms": shared.ChannelParam{If: courier.String("data.priority === 'high'")},
		},
	},
})
```

```java Java highlight={7} theme={null}
SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(UserRecipient.builder().userId("user_123").build())
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .channels(MessageChannels.builder()
            .putAdditionalProperty("sms", JsonValue.from(
                java.util.Map.of("if", "data.priority === 'high'")))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={9} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'channels' => [
      'sms' => [
        'if' => 'data.priority === \'high\'',
      ],
    ],
  ],
);
```

```csharp C# highlight={9} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Channels = new Dictionary<string, Channel>
        {
            { "sms", new Channel { If = "data.priority === 'high'" } },
        },
    },
};

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

```bash CLI highlight={5} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.channels '{"sms": {"if": "data.priority === '\''high'\''"}}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 and only use SMS when the priority is high.
```

> [!NOTE]
>
> Setting `routing` on a send drops the template's default routing conditions, so include any channel conditions you want in `message.channels`.

User preferences take precedence over channel conditions. When a user sets custom channel routing, conditions run only within their selected channels.

**3. Override a provider at send time**

Adjust how a specific provider sends this one message with `providers.<provider>.override`, without changing the template. For example, filter push tokens or set a provider-specific field:

```javascript Node.js highlight={18-19} theme={null}
const { requestId } = await courier.send.message({
  message: {
    to: {
      user_id: "user_123",
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    routing: {
      method: "all",
      channels: [
        "apn",
        "firebase-fcm",
      ],
    },
    providers: {
      "firebase-fcm": {
        override: {
          config: {
            filterByBundleId: true,
            bundleId: "com.acme.app",
          },
        },
      },
    },
  },
});
```

```python Python highlight={18-19} theme={null}
response = client.send.message(
    message={
        "to": {
            "user_id": "user_123",
        },
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "routing": {
            "method": "all",
            "channels": [
                "apn",
                "firebase-fcm",
            ],
        },
        "providers": {
            "firebase-fcm": {
                "override": {
                    "config": {
                        "filterByBundleId": True,
                        "bundleId": "com.acme.app",
                    },
                },
            },
        },
    },
)
```

```bash cURL highlight={21-22} wrap 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": "all",
        "channels": [
          "apn",
          "firebase-fcm"
        ]
      },
      "providers": {
        "firebase-fcm": {
          "override": {
            "config": {
              "filterByBundleId": true,
              "bundleId": "com.acme.app"
            }
          }
        }
      }
    }
  }'
```

```ruby Ruby highlight={18-19} theme={null}
response = courier.send_.message(
  message: {
    to: {
      user_id: "user_123"
    },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    routing: {
      method: "all",
      channels: [
        "apn",
        "firebase-fcm"
      ]
    },
    providers: {
      "firebase-fcm": {
        override: {
          config: {
            filterByBundleId: true,
            bundleId: "com.acme.app"
          }
        }
      }
    }
  }
)
```

```go Go highlight={20-21} 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{
			Channels: []shared.MessageRoutingChannelUnionParam{
				{OfString: courier.String("apn")},
				{OfString: courier.String("firebase-fcm")},
			},
			Method: "all",
		},
		Providers: shared.MessageProvidersParam{
			"firebase-fcm": shared.MessageProvidersTypeParam{
				Override: map[string]any{
					"config": map[string]any{
						"filterByBundleId": true,
						"bundleId": "com.acme.app",
					},
				},
			},
		},
	},
})
```

```java Java highlight={13-14} 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()
            .addChannel("apn")
            .addChannel("firebase-fcm")
            .method(SendMessageParams.Message.Routing.Method.ALL)
            .build())
        .providers(MessageProviders.builder()
            .putAdditionalProperty("firebase-fcm", JsonValue.from(java.util.Map.of("override", java.util.Map.of(
                    "config", java.util.Map.of(
                        "filterByBundleId", true,
                        "bundleId", "com.acme.app"
                    )
                ))))
            .build())
        .build())
    .build();
SendMessageResponse response = client.send().message(params);
```

```php PHP highlight={18-19} theme={null}
$response = $client->send->message(
  message: [
    'to' => [
      'user_id' => 'user_123',
    ],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'routing' => [
      'method' => 'all',
      'channels' => [
        'apn',
        'firebase-fcm',
      ],
    ],
    'providers' => [
      'firebase-fcm' => [
        'override' => [
          'config' => [
            'filterByBundleId' => true,
            'bundleId' => 'com.acme.app',
          ],
        ],
      ],
    ],
  ],
);
```

```csharp C# highlight={18-19} theme={null}
SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Routing = new() { Channels = ["apn", "firebase-fcm"], Method = Send::Method.All },
        Providers = new Dictionary<string, MessageProvidersType>()
        {
            {
                "firebase-fcm",
                new()
                {
                    Override = JsonSerializer.Deserialize<Dictionary<string, JsonElement>>(
                        """
                        {
                          "config": {
                            "filterByBundleId": true,
                            "bundleId": "com.acme.app"
                          }
                        }
                        """
                    ),
                }
            },
        },
    },
};

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

```bash CLI highlight={6} wrap theme={null}
courier send message \
  --api-key "$COURIER_API_KEY" \
  --message.to '{"user_id": "user_123"}' \
  --message.template nt_01kx4h2jdafq8bk9aftxak4b40 \
  --message.routing '{"method": "all", "channels": ["apn", "firebase-fcm"]}' \
  --message.providers '{"firebase-fcm": {"override": {"config": {"filterByBundleId": true, "bundleId": "com.acme.app"}}}}'
```

```text MCP theme={null}
With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 with a provider-specific override.
```

See [Push providers](https://www.courier.com/docs/integrations/push/overview.md#channel-overrides) for the push override fields, and each [provider integration](https://www.courier.com/docs/integrations/overview.md) for its override options.

**4. Check the logs**

Send with your settings and open the message in [Logs](https://app.courier.com/logs). Confirm the channels that sent, and that each channel condition behaved as expected.
