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

# Fall back to another channel when a message isn't delivered

> Send an SMS when an email bounces, or an email when a push isn't delivered. One Journey waits for the result, so you run no webhook handler.

Send an SMS when an email bounces, or an email when a push doesn't reach the device. A Journey sends the first message, waits, and sends the backup only if Courier recorded that the first one wasn't delivered.

Once delivery tracking is on for your provider, Courier receives its delivery events and marks a bounced email `UNDELIVERABLE`. You don't run a webhook route, verify signatures, or keep a table of pending sends.

## Choose failover or a Journey

Both move a message to another channel, at different moments:

| | Routing failover | A fallback Journey |
| - | - | - |
| **Reacts to** | An error while handing the message to a provider: the provider is down, rejects the request, or the user has no address for that channel | The delivery result the provider reports afterward: a bounced email, or a push the device never confirmed |
| **When** | At send time, within the same request | After a wait you set |
| **Set it up** | Automatic between providers on one channel. To move to the next channel, send with `routing.method: "single"`. See [Routing](https://www.courier.com/docs/send/routing.md#failover) | The Journey below |

A bounce arrives after the provider has accepted the email, so routing failover never sees it. Use the Journey for anything decided by delivery.

## Prerequisites

* [A Courier API key](https://app.courier.com/settings/api-keys)
* [A connected email provider](https://www.courier.com/docs/integrations/email/overview.md) with delivery tracking on, such as the [SendGrid event webhook](https://www.courier.com/docs/integrations/email/sendgrid.md#delivery-tracking). Without tracking, an email stays at `SENT` and never reads as `UNDELIVERABLE`. See [Delivery tracking is per provider](https://www.courier.com/docs/send/statuses.md#delivery-tracking-is-per-provider).
* [A connected SMS provider](https://www.courier.com/docs/integrations/sms/overview.md)
* [Your users stored in Courier](https://www.courier.com/docs/guides/import-your-users.md) with an email address and a phone number

## Send an SMS when an email bounces

**1. Create the Journey**

Open [Journeys](https://app.courier.com/orchestration/journeys), select **New Journey**, name it `delivery-fallback`, and choose the **API Invoke** trigger. Add a `report_url` field to the trigger schema so both messages can link to the same place.

**2. Send the email**

Add a **send** node on the **Email** channel and write the message, using `{{report_url}}` for the link. Publish its template.

**3. Wait for the delivery result**

Add a **delay** node set to **Duration**, such as 1 hour. Courier updates the email's status as your provider reports it, and the next node reads the status when the wait ends.

Pick the longest wait you're willing to make the user sit through before the SMS. A bounce your provider reports after the wait ends doesn't trigger the SMS.

**4. Send the SMS only if the email bounced**

Add an **SMS** send node with the same message and one condition: `send_status.<email node ID>` **was** `UNDELIVERABLE`. The node ID is the email node's `id`. Over the API, it comes back when you create or replace the Journey, and [`GET /journeys/{templateId}`](https://www.courier.com/docs/api-reference/journeys/fetch-a-journey-by-id) returns it once the Journey is published.

`UNDELIVERABLE` matches only that exact status, which your provider sets for a bounce or a dropped message. Users whose email went through skip the SMS.

To send the SMS unless delivery is confirmed, use **was not** `DELIVERED` instead. That also covers an email still at `SENT` when the wait ends, so it needs delivery tracking working, or every user gets the SMS too.

**5. Publish**

Publish the SMS template, then the Journey, and copy its ID from the editor.

## Send an email when a push isn't delivered

The same shape works the other way, for a push that doesn't reach the device. Use a **Push** send node first, then a delay, then an **Email** send node with the condition `send_status.<push node ID>` **was not** `DELIVERED`.

A push reaches `DELIVERED` only when your app reports it, through a [Courier mobile SDK](https://www.courier.com/docs/sdk-libraries/sdks-overview.md) or the payload's [`trackingUrl`](https://www.courier.com/docs/integrations/push/overview#tracking). This works with [Expo](https://www.courier.com/docs/integrations/push/expo.md) and every other push provider. Without that report, every push stays at `SENT` and every user also gets the email.

A user with no device tokens gets no push, and the email goes to them. The same happens if the push node was skipped: the condition reads as not delivered.

## Trigger it from your app

Call [`POST /journeys/{templateId}/invoke`](https://www.courier.com/docs/api-reference/journeys/invoke-a-journey) where you'd have sent the email. Replace `delivery-fallback` with the Journey ID you copied, or the alias if you set one.

```javascript Node.js theme={null}
const journeysInvokeResponse = await client.journeys.invoke('delivery-fallback', {
  user_id: 'user_123',
  data: {
    report_url: 'https://app.example.com/reports/42',
  },
  'Idempotency-Key': 'report-ready-report_42',
});
```

```python Python theme={null}
journeys_invoke_response = client.journeys.invoke(
    template_id="delivery-fallback",
    user_id="user_123",
    data={
        "report_url": "https://app.example.com/reports/42",
    },
    idempotency_key="report-ready-report_42",
)
```

```bash cURL theme={null}
curl -X POST https://api.courier.com/journeys/delivery-fallback/invoke \
  -H "Authorization: Bearer $COURIER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: report-ready-report_42" \
  -d "{
    \"user_id\": \"user_123\",
    \"data\": {
      \"report_url\": \"https://app.example.com/reports/42\"
    }
  }"
```

```ruby Ruby theme={null}
journeys_invoke_response = courier.journeys.invoke(
  "delivery-fallback",
  user_id: "user_123",
  data: {
    report_url: "https://app.example.com/reports/42",
  },
  idempotency_key: "report-ready-report_42"
)
```

```go Go theme={null}
journeysInvokeResponse, err := client.Journeys.Invoke(
	context.TODO(),
	"delivery-fallback",
	courier.JourneyInvokeParams{
		JourneysInvokeRequest: courier.JourneysInvokeRequestParam{
			UserID: courier.String("user_123"),
			Data: map[string]any{
				"report_url": "https://app.example.com/reports/42",
			},
		},
		IdempotencyKey: courier.String("report-ready-report_42"),
	},
)
```

```java Java theme={null}
JourneyInvokeParams params = JourneyInvokeParams.builder()
    .templateId("delivery-fallback")
    .journeysInvokeRequest(JourneysInvokeRequest.builder()
        .userId("user_123")
        .data(JourneysInvokeRequest.Data.builder()
            .putAdditionalProperty("report_url", JsonValue.from("https://app.example.com/reports/42"))
            .build())
        .build())
    .idempotencyKey("report-ready-report_42")
    .build();
JourneysInvokeResponse journeysInvokeResponse = client.journeys().invoke(params);
```

```php PHP theme={null}
$journeysInvokeResponse = $client->journeys->invoke(
  'delivery-fallback',
  userID: 'user_123',
  data: [
    'report_url' => 'https://app.example.com/reports/42',
  ],
  idempotencyKey: 'report-ready-report_42',
);
```

```csharp C# theme={null}
JourneyInvokeParams parameters = new()
{
    TemplateID = "delivery-fallback",
    UserID = "user_123",
    Data = new Dictionary<string, JsonElement>()
    {
        { "report_url", JsonSerializer.SerializeToElement("https://app.example.com/reports/42") },
    },
    IdempotencyKey = "report-ready-report_42",
};

var journeysInvokeResponse = await client.Journeys.Invoke(parameters);
```

```bash CLI theme={null}
courier journeys invoke \
  --api-key "$COURIER_API_KEY" \
  --template-id delivery-fallback \
  --user-id user_123 \
  --idempotency-key report-ready-report_42 \
  --data "{\"report_url\":\"https://app.example.com/reports/42\"}"
```

```text MCP theme={null}
With Courier MCP, start the delivery-fallback journey for user_123 with report_url https://app.example.com/reports/42.
```

The idempotency key makes a retried request return the same run instead of sending twice. Build it from the thing you're notifying about, such as the report's ID.

## Verify

**1. Bounce an email on purpose**

Invoke the Journey for a test user whose address you know bounces: a mailbox that doesn't exist, on a domain with no catch-all. Send from a test sending domain, not your production one, so test bounces don't count against its reputation. For a faster test, publish a copy of the Journey with a 2-minute delay and invoke the copy.

After one bounce, SendGrid suppresses that address, so later tests to it are dropped. A dropped email also reads as `UNDELIVERABLE`, so the SMS still goes out.

**2. Follow the run**

Open the Journey's **Logs** tab and select the run. The email node's message shows `UNDELIVERABLE`, and the SMS node shows its condition passed and the SMS sent. Over the API, [`GET /journeys/runs/{run_id}/steps`](https://www.courier.com/docs/api-reference/journeys/list-steps-for-a-journey-run) returns the same steps.

**3. Check the happy path**

Invoke it again for a user with a working address. The email is delivered and the SMS node is skipped.

## FAQ

> [accordion] Does routing failover send an SMS when an email bounces?
>
> Routing failover acts when a provider rejects the send or errors. A bounce is reported after the provider accepted the email, so it takes a Journey with a `send_status` condition, as above.

> [accordion] Why did every user get the SMS?
>
> The condition read a status other than the one you expected. With **was not** `DELIVERED`, an email still at `SENT` passes, which happens when delivery tracking isn't set up. Check the email's status in [Logs](https://www.courier.com/docs/monitor/logs.md), and set up tracking for your provider.

> [accordion] Why did a bounced user get no SMS?
>
> The bounce arrived after the delay ended, or the provider reported it as something other than a bounce. Lengthen the delay, and check the email's timeline in [Logs](https://www.courier.com/docs/monitor/logs.md).

> [accordion] Can I fall back across more than two channels?
>
> Chain the pattern: after the SMS node, add another delay and a send node with two conditions in one group, so both must hold: `send_status.<email node ID>` **was** `UNDELIVERABLE`, and `send_status.<SMS node ID>` **was not** `DELIVERED`.
>
> Keep the email condition. When the email is delivered, the SMS node is skipped, and a skipped node reads as not delivered. Without the email condition, the third message would go to every user whose email arrived.

Every condition field and operator is in the [branch node reference](https://www.courier.com/docs/journeys/nodes/branch.md). For the full list of message statuses, see [Message statuses](https://www.courier.com/docs/send/statuses.md).
