Send Multi-Channel Notifications from an AI Agent

In this tutorial, you’ll build a TypeScript function that lets an AI agent send notifications across multiple channels with a single API call. The agent decides what to communicate and how urgent it is. Courier handles channel selection, failover, and delivery.

Prerequisites

Before you start, make sure you have:

Node.js 18+ installed
A Courier account (sign up free)
Your Courier API key from Settings > API Keys
A test user profile in Courier with an email address (create one in the Users page or via the API)

Which channels work out of the box?

Not every channel requires provider setup. Here’s what you can use right away and what needs configuration:

Channel	Ready out of the box?	Setup needed
Inbox	Yes	None. Courier’s in-app inbox works immediately.
Email	Yes (test mode)	Courier provides a built-in email provider for testing. For production, add a provider like SendGrid or AWS SES.
Push	No	Requires a push provider (Firebase, APNs) and device tokens on user profiles.
SMS	No	Requires an SMS provider (Twilio, Vonage) and phone numbers on user profiles.

Channels without a configured provider show as Unroutable in the logs. Courier skips them automatically and tries the next channel in the list. Start with "low" urgency (inbox only) and add channels as you set up providers.

Project setup

Initialize the project

Create a new directory and install the Courier SDK:

mkdir agent-courier-notifications && cd agent-courier-notifications
npm init -y
npm install @trycourier/courier dotenv
npm install typescript tsx --save-dev
npx tsc --init

Configure your API key

Create a .env file in your project root:

COURIER_API_KEY=your_courier_api_key

Create the project structure

agent-courier-notifications/
├── src/
│   └── send-notification.ts
├── .env
├── package.json
└── tsconfig.json

Understanding the routing model

Every Courier send call accepts a routing object with two fields:

routing: {
  method: "all" | "single",
  channels: ["email", "sms", "push", "inbox"]
}

Method	Behavior
`single`	Try each channel in order, stop at the first successful delivery
`all`	Deliver to every channel in the array simultaneously

The channel array is your priority list. For single, Courier works through it top to bottom. For all, every channel fires at once.

For a full walkthrough of routing configuration (including the visual designer), see How to configure multi-channel routing.

Pattern 1: Urgency-based routing

The most common pattern for agent-driven notifications. Instead of hardcoding a channel, the agent expresses urgency and a helper function maps it to a routing strategy. Create src/send-notification.ts:

import Courier from "@trycourier/courier";
import "dotenv/config";

const courier = new Courier();

function routingForUrgency(urgency: string) {
  const strategies: Record<string, { method: "all" | "single"; channels: string[] }> = {
    critical: { method: "all", channels: ["email", "sms", "push", "inbox"] },
    high:     { method: "single", channels: ["push", "email", "inbox"] },
    normal:   { method: "single", channels: ["email", "inbox"] },
    low:      { method: "single", channels: ["inbox"] },
  };
  return strategies[urgency] ?? strategies.normal;
}

export async function sendNotification(
  userId: string,
  title: string,
  body: string,
  urgency: string
) {
  const routing = routingForUrgency(urgency);

  const { requestId } = await courier.send.message({
    message: {
      to: { user_id: userId },
      content: { title, body },
      routing,
    },
  });

  return { requestId, channels: routing.channels, method: routing.method };
}

Here’s what each urgency level does:

Urgency	Method	Channels	When to use
`critical`	`all`	email, SMS, push, inbox	Security alerts, outages, account compromises
`high`	`single`	push → email → inbox	Time-sensitive operational alerts
`normal`	`single`	email → inbox	Reports, digests, routine updates
`low`	`single`	inbox	Informational, non-time-sensitive

Test it

Add a quick test script at the bottom of send-notification.ts (or in a separate file):

async function main() {
  const urgency = process.argv[2] || "low";
  const result = await sendNotification(
    "test_user_123",
    "Weekly report ready",
    "Your weekly usage report is now available.",
    urgency
  );
  console.log("Sent:", result);
}

main().catch(console.error);

Start with low urgency to confirm your setup works. This sends to inbox only, which requires no provider configuration:

npx tsx src/send-notification.ts low

Check Courier Logs to confirm the notification was delivered to inbox. Then try higher urgency levels as you configure additional channels:

npx tsx src/send-notification.ts normal    # email + inbox
npx tsx src/send-notification.ts high      # push → email → inbox
npx tsx src/send-notification.ts critical  # all channels at once

If a channel shows as Unroutable in the logs, that just means you haven’t configured a provider for it yet. With method: "single", Courier automatically skips to the next channel in the list, so your notification still gets delivered through whichever channels are set up.

Pattern 2: Channel failover

Some users don’t have push tokens configured. Some haven’t verified their phone number. With method: "single", Courier attempts each channel in order and stops at the first success:

const { requestId } = await courier.send.message({
  message: {
    to: { user_id: userId },
    content: { title, body },
    routing: {
      method: "single",
      channels: ["push", "email", "sms", "inbox"],
    },
  },
});

If push fails (no device token), Courier tries email. If email fails (bad address), it tries SMS. If SMS fails, it falls back to inbox. The agent doesn’t need to check user profiles before sending.

The requestId returned by the send call lets you check delivery status later using the Messages API. This is useful for agents that need to confirm a notification landed before continuing.

Pattern 3: Provider failover

Channel failover handles “which channel.” Provider failover handles “which service within a channel.” If your primary email provider goes down, Courier can silently retry through a backup. Add a channels object to configure per-channel provider ordering:

const { requestId } = await courier.send.message({
  message: {
    to: { user_id: userId },
    content: { title, body },
    routing: {
      method: "single",
      channels: ["email", "push", "inbox"],
    },
    channels: {
      email: {
        providers: ["sendgrid", "ses"],
        routing_method: "single",
      },
    },
  },
});

This gives you two layers of failover:

Channel level: email → push → inbox
Provider level (within email): SendGrid → AWS SES

If SendGrid returns a 5xx, Courier retries through SES automatically.

You can configure provider failover for any channel, not just email. For example, set up Twilio as a primary SMS provider with Vonage as a backup.

Pattern 4: Template-based multi-channel

For notifications that need branded designs, channel-specific copy, or complex layouts, use a Courier template instead of inline content. Design the template once in the template designer, and Courier renders the appropriate version for each channel.

const { requestId } = await courier.send.message({
  message: {
    to: { user_id: userId },
    template: "DEPLOYMENT_ALERT",
    data: {
      service: "api-server",
      environment: "production",
      exitCode: 1,
      timestamp: new Date().toISOString(),
    },
    routing: {
      method: "all",
      channels: ["email", "push", "inbox"],
    },
  },
});

The data object passes dynamic values into your template variables. The email version can include a full HTML layout with error details, the push notification can be a short summary, and the inbox message can include action buttons.

To create the DEPLOYMENT_ALERT template, go to Templates, click New, and add channel blocks for each delivery channel. Use {service}, {environment}, and {exitCode} as template variables.

Exposing to your agent

The sendNotification function from Pattern 1 works as a tool in any agent framework. Here are three ways to connect it:

Option 1: Courier MCP server

If your agent runs in Cursor, Claude Code, or another MCP-compatible environment, the Courier MCP server exposes a send_message tool that already supports routing, channels, and template fields. No custom code needed. Add to your .cursor/mcp.json:

{
  "mcpServers": {
    "courier": {
      "url": "https://mcp.courier.com",
      "headers": {
        "api_key": "your_courier_api_key"
      }
    }
  }
}

Option 2: Courier CLI

For agents that work through shell commands, use courier send message with the same JSON structure:

courier send message --message '{
  "to": {"user_id": "test_user_123"},
  "content": {"title": "Deployment failed", "body": "Exit code 1"},
  "routing": {"method": "all", "channels": ["email", "push", "inbox"]}
}'

See the CLI reference for installation and full command documentation.

Option 3: Custom tool definition

Wrap sendNotification as a tool in your framework of choice. The function signature maps directly to a tool schema: userId, title, body, and urgency as parameters, with the urgency descriptions guiding the LLM’s selection. This works with OpenAI function calling, Vercel AI SDK, LangChain, or any framework that supports structured tool definitions.

Verify delivery

After sending, check delivery status in two ways:

Courier Logs UI: Go to app.courier.com/logs to see the full delivery timeline for each notification, including which channels were attempted, which succeeded, and which providers were used.
Messages API: Query delivery status programmatically:

const message = await courier.messages.retrieve("your_request_id");
console.log(message.status); // DELIVERED, SENT, UNDELIVERABLE, etc.

In the logs, you’ll see one entry per channel attempted. Common statuses:

Status	Meaning
Delivered	The provider accepted and delivered the notification
Sent	The provider accepted the notification (delivery confirmation pending)
Unroutable	No provider is configured for this channel. Expected if you haven’t set up that channel yet.
Undeliverable	A provider is configured but delivery failed (bad address, expired token, etc.)

What’s next

Configure multi-channel routing

Set up routing rules in the Send API and the visual designer

Agent quickstart

Set up your AI agent with Courier’s MCP server, CLI, and Skills

CLI reference

Send and manage notifications from the command line

Send API reference

Full API documentation for the Send endpoint

Send Messages

Design Messages

User Journeys

Inbox & Preferences

Deploying and Debugging

Migrate to Courier

Send Multi-Channel Notifications from an AI Agent

Prerequisites

Which channels work out of the box?

Project setup

Understanding the routing model

Pattern 1: Urgency-based routing

Test it

Pattern 2: Channel failover

Pattern 3: Provider failover

Pattern 4: Template-based multi-channel

Exposing to your agent

Option 1: Courier MCP server

Option 2: Courier CLI

Option 3: Custom tool definition

Verify delivery

What’s next

Configure multi-channel routing

Agent quickstart

CLI reference

Send API reference

​Prerequisites

​Which channels work out of the box?

​Project setup

​Understanding the routing model

​Pattern 1: Urgency-based routing

​Test it

​Pattern 2: Channel failover

​Pattern 3: Provider failover

​Pattern 4: Template-based multi-channel

​Exposing to your agent

​Option 1: Courier MCP server

​Option 2: Courier CLI

​Option 3: Custom tool definition

​Verify delivery

​What’s next

Configure multi-channel routing

Agent quickstart

CLI reference

Send API reference

Prerequisites

Which channels work out of the box?

Project setup

Understanding the routing model

Pattern 1: Urgency-based routing

Test it

Pattern 2: Channel failover

Pattern 3: Provider failover

Pattern 4: Template-based multi-channel

Exposing to your agent

Option 1: Courier MCP server

Option 2: Courier CLI

Option 3: Custom tool definition

Verify delivery

What’s next