Routing strategies

A routing strategy is a saved routing setup: the channels a template sends on, their fallback order, and the providers behind each one. Templates point at a strategy by ID, so one edit changes delivery for every template that uses it.

A routing strategy in Design Studio: email always sends, then SMS, Slack, MS Teams, In-App, and push as fallbacks, with a flowchart of the route

What a strategy holds

A strategy carries the same routing object you’d pass on a send, plus the per-channel and per-provider settings around it. Its ID starts with rs_.

Field	What it sets
`name`	The label in the routing selector
`routing`	The channel list and `method`, as described in How routing works
`channels`	Per channel: `providers` in priority order, `routing_method`, an `if` condition, and an `override`
`providers`	Per provider: an `if` condition and an `override` that apply on every channel
`description`, `tags`	Your own labels for finding the strategy later

Build a strategy in Design Studio

Open a template and click the routing selector in the toolbar. It lists the workspace’s strategies, with a pencil icon to edit each one and Add new routing to create one. Picking a strategy attaches it to the template.

The routing selector open in the Design Studio toolbar, listing three strategies with edit icons and an Add new routing option

Give the strategy a Routing name, then pick a Routing scheme:

Basic sends on every channel you switch on, at the same time.
Advanced splits channels into two lists. Everything under Always send to the following channels (min. 1) sends. If the last of those fails, Courier tries the channels under If the last above fails, send to the first successful one below, in order, until one delivers.

Drag channels to change their order. The flowchart beside the lists draws the route as you build it. To set the provider order for a channel, click the pencil icon next to it. Under Routing scheme, To the best of tries providers in the order you drag them into, and To all sends through every one. Add more integrations puts another provider on the channel. The Conditions tab sets when the channel is used, on every template that shares the strategy. Click Create routing strategy to save a new one, or Save and close after an edit. Delete stays disabled while any template uses the strategy, so move those templates to another strategy first.

Manage strategies with the API

Create a strategy

POST /routing-strategies takes a name and a routing object. This strategy tries email, then SMS, and sends email through SendGrid with SES as the backup:

const strategy = await courier.routingStrategies.create({
  name: "Email with SMS fallback",
  routing: { method: "single", channels: ["email", "sms"] },
  channels: {
    email: { providers: ["sendgrid", "ses"] },
  },
  tags: ["production"],
});

strategy = client.routing_strategies.create(
    name="Email with SMS fallback",
    routing={"method": "single", "channels": ["email", "sms"]},
    channels={
        "email": {"providers": ["sendgrid", "ses"]},
    },
    tags=["production"],
)

curl -X POST https://api.courier.com/routing-strategies \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Email with SMS fallback",
    "routing": { "method": "single", "channels": ["email", "sms"] },
    "channels": {
      "email": { "providers": ["sendgrid", "ses"] }
    },
    "tags": ["production"]
  }'

strategy = courier.routing_strategies.create(
  name: "Email with SMS fallback",
  routing: {method: :single, channels: ["email", "sms"]},
  channels: {
    email: {providers: ["sendgrid", "ses"]}
  },
  tags: ["production"]
)

strategy, err := client.RoutingStrategies.New(context.TODO(), courier.RoutingStrategyNewParams{
	RoutingStrategyCreateRequest: courier.RoutingStrategyCreateRequestParam{
		Name: "Email with SMS fallback",
		Routing: shared.MessageRoutingParam{
			Method: shared.MessageRoutingMethodSingle,
			Channels: []shared.MessageRoutingChannelUnionParam{
				{OfString: courier.String("email")},
				{OfString: courier.String("sms")},
			},
		},
		Channels: shared.MessageChannelsParam{
			"email": shared.ChannelParam{Providers: []string{"sendgrid", "ses"}},
		},
		Tags: []string{"production"},
	},
})

RoutingStrategyGetResponse strategy = client.routingStrategies().create(
    RoutingStrategyCreateRequest.builder()
        .name("Email with SMS fallback")
        .routing(MessageRouting.builder()
            .method(MessageRouting.Method.SINGLE)
            .addChannel("email")
            .addChannel("sms")
            .build())
        .channels(MessageChannels.builder()
            .putAdditionalProperty("email", JsonValue.from(java.util.Map.of(
                "providers", java.util.List.of("sendgrid", "ses"))))
            .build())
        .addTag("production")
        .build());

$strategy = $client->routingStrategies->create(
  name: 'Email with SMS fallback',
  routing: ['method' => 'single', 'channels' => ['email', 'sms']],
  channels: [
    'email' => ['providers' => ['sendgrid', 'ses']],
  ],
  tags: ['production'],
);

RoutingStrategyCreateParams parameters = new()
{
    Name = "Email with SMS fallback",
    Routing = new() { Method = Method.Single, Channels = ["email", "sms"] },
    Channels = new Dictionary<string, Channel>()
    {
        { "email", new() { Providers = ["sendgrid", "ses"] } },
    },
    Tags = ["production"],
};

var strategy = await client.RoutingStrategies.Create(parameters);

courier routing-strategies create \
  --api-key "$COURIER_API_KEY" \
  --name "Email with SMS fallback" \
  --routing '{"method": "single", "channels": ["email", "sms"]}' \
  --channels '{"email": {"providers": ["sendgrid", "ses"]}}' \
  --tag production

With Courier MCP, create a routing strategy named "Email with SMS fallback" that tries email first, then SMS, and sends email through SendGrid with SES as the backup.

The response carries the new strategy’s id. Set it as routing.strategy_id when you create or replace a template, as shown in Manage templates with the API.

Switch providers on every template at once

Every template that uses a strategy picks up a change on its next send, so one edit moves all of them to a new provider. Courier reads the strategy at send time, so no template needs republishing. To see which templates a change reaches, call GET /routing-strategies/{id}/notifications first. PUT /routing-strategies/{id} takes the complete strategy and clears any field you leave out, so send every field you want to keep. This puts SES ahead of SendGrid:

const strategy = await courier.routingStrategies.replace("rs_01kx4h2jdafq8bk9amzvy6hbv0", {
  name: "Email with SMS fallback",
  routing: { method: "single", channels: ["email", "sms"] },
  channels: {
    email: { providers: ["ses", "sendgrid"] },
  },
  tags: ["production"],
});

strategy = client.routing_strategies.replace(
    id="rs_01kx4h2jdafq8bk9amzvy6hbv0",
    name="Email with SMS fallback",
    routing={"method": "single", "channels": ["email", "sms"]},
    channels={
        "email": {"providers": ["ses", "sendgrid"]},
    },
    tags=["production"],
)

curl -X PUT https://api.courier.com/routing-strategies/rs_01kx4h2jdafq8bk9amzvy6hbv0 \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Email with SMS fallback",
    "routing": { "method": "single", "channels": ["email", "sms"] },
    "channels": {
      "email": { "providers": ["ses", "sendgrid"] }
    },
    "tags": ["production"]
  }'

strategy = courier.routing_strategies.replace(
  "rs_01kx4h2jdafq8bk9amzvy6hbv0",
  name: "Email with SMS fallback",
  routing: {method: :single, channels: ["email", "sms"]},
  channels: {
    email: {providers: ["ses", "sendgrid"]}
  },
  tags: ["production"]
)

strategy, err := client.RoutingStrategies.Replace(
	context.TODO(),
	"rs_01kx4h2jdafq8bk9amzvy6hbv0",
	courier.RoutingStrategyReplaceParams{
		RoutingStrategyReplaceRequest: courier.RoutingStrategyReplaceRequestParam{
			Name: "Email with SMS fallback",
			Routing: shared.MessageRoutingParam{
				Method: shared.MessageRoutingMethodSingle,
				Channels: []shared.MessageRoutingChannelUnionParam{
					{OfString: courier.String("email")},
					{OfString: courier.String("sms")},
				},
			},
			Channels: shared.MessageChannelsParam{
				"email": shared.ChannelParam{Providers: []string{"ses", "sendgrid"}},
			},
			Tags: []string{"production"},
		},
	},
)

RoutingStrategyGetResponse strategy = client.routingStrategies().replace(
    RoutingStrategyReplaceParams.builder()
        .id("rs_01kx4h2jdafq8bk9amzvy6hbv0")
        .routingStrategyReplaceRequest(RoutingStrategyReplaceRequest.builder()
            .name("Email with SMS fallback")
            .routing(MessageRouting.builder()
                .method(MessageRouting.Method.SINGLE)
                .addChannel("email")
                .addChannel("sms")
                .build())
            .channels(MessageChannels.builder()
                .putAdditionalProperty("email", JsonValue.from(java.util.Map.of(
                    "providers", java.util.List.of("ses", "sendgrid"))))
                .build())
            .addTag("production")
            .build())
        .build());

$strategy = $client->routingStrategies->replace(
  'rs_01kx4h2jdafq8bk9amzvy6hbv0',
  name: 'Email with SMS fallback',
  routing: ['method' => 'single', 'channels' => ['email', 'sms']],
  channels: [
    'email' => ['providers' => ['ses', 'sendgrid']],
  ],
  tags: ['production'],
);

RoutingStrategyReplaceParams parameters = new()
{
    ID = "rs_01kx4h2jdafq8bk9amzvy6hbv0",
    Name = "Email with SMS fallback",
    Routing = new() { Method = Method.Single, Channels = ["email", "sms"] },
    Channels = new Dictionary<string, Channel>()
    {
        { "email", new() { Providers = ["ses", "sendgrid"] } },
    },
    Tags = ["production"],
};

var strategy = await client.RoutingStrategies.Replace(parameters);

courier routing-strategies replace \
  --api-key "$COURIER_API_KEY" \
  --id rs_01kx4h2jdafq8bk9amzvy6hbv0 \
  --name "Email with SMS fallback" \
  --routing '{"method": "single", "channels": ["email", "sms"]}' \
  --channels '{"email": {"providers": ["ses", "sendgrid"]}}' \
  --tag production

With Courier MCP, update routing strategy rs_01kx4h2jdafq8bk9amzvy6hbv0 so email sends through SES first and SendGrid second, keeping everything else the same.

List and archive strategies

GET /routing-strategies returns each strategy’s name and tags. GET /routing-strategies/{id} returns its full configuration. DELETE /routing-strategies/{id} returns 409 while any template still uses the strategy.

FAQ

Do I need to republish templates after editing a routing strategy?

Templates don’t need republishing after a strategy edit. A template stores only the strategy’s ID, and Courier reads the strategy on every send, so the next message uses the new configuration.

Can one send use different routing from its template's strategy?

A send can pass its own routing object, which replaces the strategy’s channel list and method for that message. The strategy’s provider order and channel conditions still apply. See where routing is set.

Get started

Send messages

Journeys

Broadcasts

Design

In-app

Recipients

Tenants

Monitoring

Workspaces

Resources

Routing strategies

What a strategy holds

Build a strategy in Design Studio

Manage strategies with the API

Create a strategy

Switch providers on every template at once

List and archive strategies

FAQ

​What a strategy holds

​Build a strategy in Design Studio

​Manage strategies with the API

​Create a strategy

​Switch providers on every template at once

​List and archive strategies

​FAQ

What a strategy holds

Build a strategy in Design Studio

Manage strategies with the API

Create a strategy

Switch providers on every template at once

List and archive strategies

FAQ