Skip to main content
Your AI agent decides who to tell and when, and Courier handles channels, routing, failover, preferences, and delivery logs. Give the agent Courier in one of two ways:
  • A Courier tool gives you tight control. You write one function that sends one published template, and the agent fills in only the fields your schema allows.
  • The Courier MCP server gives the agent the full API: 170+ tools for sending, users, templates, and logs, with no tool code to write.
Build with a Test environment key. Test’s built-in email provider only delivers to the address you signed up with, so until you connect your own provider, an agent can’t reach a real customer by mistake.

Prerequisites

Set up the project

In a new folder, install the AI SDK, its MCP client, and the Courier SDK:
Set both keys in the shell that runs the agent:
The model strings below route through Vercel AI Gateway, the AI SDK’s default provider, which reads AI_GATEWAY_API_KEY. Any AI SDK provider works in its place.

Give the agent a Courier tool

1

Write the agent

The tool sends one template and takes three inputs. The AI SDK validates each call against inputSchema before execute runs, so the agent can’t send a status other than in_progress or resolved.
agent.ts
The key in tools is the name the model calls. stopWhen lets the model call the tool and then write its reply. Without it, generateText stops after the first step.The Courier SDK retries failed requests, and the Idempotency-Key makes those retries safe: a retried request returns the first response instead of sending twice. Use a fresh key for each send. A key built from the ticket and status would replay a failed first attempt, and silence a second notice with the same status, for 25 hours.
2

Run it

The agent calls send_ticket_update and replies with the requestId. The template holds the content, so the agent picks the recipient and the moment without writing the message.

Connect the Courier MCP server

1

Point the agent at the server

Create an MCP client with the HTTP transport and your key in the api_key header, then hand its tools to generateText.
agent.ts
mcpClient.tools() returns every Courier tool, keyed by name. Hand the agent only the ones it needs, here sending a template and tracing a message, so a support agent can’t reach write tools like profile deletes or broadcasts. Close the client when the run ends.The MCP send tools take a user_id or a list_id, not an email address, so the customer needs a saved profile.
2

Run it

The agent calls send_message_template and replies with the requestId.

Ask a person for approval

Send a template with an action button to Slack, Microsoft Teams, or the Inbox, and point the button at a URL in your app. The click reaches your app, not Courier, so record the decision there and resume the agent. The , , , and pages cover each channel.

Verify

1

Find the request in Logs

Copy the requestId from the agent’s reply, open , and find that request. Logs are per environment, so a Test send appears only in Test logs.
2

Confirm it delivered

Expand the message timeline and confirm the provider accepted it. A channel with no configured provider shows as UNROUTABLE, so start with the inbox channel, which needs no setup.

Next steps

  • to test sends from Claude Code, Cursor, or Codex
  • for every tool the server exposes
  • for every field a send accepts
  • , so a template mapped to a subscription topic respects each customer’s opt-outs