Send a message

A send is one API call. Name who it goes to and what it says. Courier renders it, applies preferences, routes, and delivers.

const { requestId } = await client.send.message({
  message: {
    to: { user_id: 'user_123' },
    template: 'nt_01kx4h2jdafq8bk9aftxak4b40',
    data: { name: 'Sarah Bennett' },
  },
});

response = client.send.message(
    message={
        "to": {"user_id": "user_123"},
        "template": "nt_01kx4h2jdafq8bk9aftxak4b40",
        "data": {"name": "Sarah Bennett"},
    },
)

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",
      "data": { "name": "Sarah Bennett" }
    }
  }'

response = courier.send_.message(
  message: {
    to: { user_id: "user_123" },
    template: "nt_01kx4h2jdafq8bk9aftxak4b40",
    data: { name: "Sarah Bennett" }
  }
)

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"),
		Data: map[string]any{
			"name": "Sarah Bennett",
		},
	},
})

SendMessageParams params = SendMessageParams.builder()
    .message(SendMessageParams.Message.builder()
        .to(JsonValue.from(java.util.Map.of("user_id", "user_123")))
        .template("nt_01kx4h2jdafq8bk9aftxak4b40")
        .data(JsonValue.from(java.util.Map.of("name", "Sarah Bennett")))
        .build())
    .build();
client.send().message(params);

$response = $client->send->message(
  message: [
    'to' => ['userID' => 'user_123'],
    'template' => 'nt_01kx4h2jdafq8bk9aftxak4b40',
    'data' => ['name' => 'Sarah Bennett'],
  ],
);

SendMessageParams parameters = new()
{
    Message = new()
    {
        To = new UserRecipient { UserID = "user_123" },
        Template = "nt_01kx4h2jdafq8bk9aftxak4b40",
        Data = new Dictionary<string, JsonElement>()
        {
            { "name", JsonSerializer.SerializeToElement("Sarah Bennett") },
        },
    },
};

await client.Send.Message(parameters);

courier send message \
  --api-key "$COURIER_API_KEY" \
  --message '{"to":{"user_id":"user_123"},"template":"nt_01kx4h2jdafq8bk9aftxak4b40","data":{"name":"Sarah Bennett"}}'

With Courier MCP, send my nt_01kx4h2jdafq8bk9aftxak4b40 template to user_123 with their name.

The response returns a requestId, not a delivery result. Find it in to confirm the message rendered and delivered.

Prerequisites

, and or curl
, for the nt_ id in the call above
, or their contact details inline in to
for the channel it goes out on. Test email and the need none.

Three ways to send

All three send the same content: a you design once. What differs is what starts the send.

1. Templates

Use a template when your application triggers the send. A receipt, a password reset, an alert. Your app calls the API with a recipient and a template, like the example above. The template holds what the message says on every channel, plus its routing and brand settings. Your app supplies data, and the template’s render each recipient’s own version. That split keeps a send small. Content changes ship by publishing the template, with no deploy.

Design a Template

Build it in the visual editor, or manage it as JSON over the Templates API.

2. Broadcasts

Use a broadcast when you choose the moment. One message to a whole , sent now or on a schedule. You pick the group, and Courier fans it out.

Send a Broadcast

Reach a saved list or audience in one send.

3. Journeys

Use a journey when the send happens later, or depends on what the user does. A multi-step flow that runs per user, with delays, branching, and enrichment between steps. A user event or an API call starts it, and the journey decides what comes next.

Build a Journey

Lay out steps, delays, and branches in the visual builder.

	Templates	Broadcasts	Journeys
Shape	One message	One message to a group	Multi-step flow, per user
Started by	Your API call	You, now or scheduled	A user event or API call
Timing	Immediate, or a delay	Now or scheduled	Delays and waits between steps
Logic	In your code	None	Built-in branching
Best for	Transactional messages	Newsletters, announcements	Onboarding, digests, re-engagement

How it works

Every send is one message object posted to , whichever SDK you call it from. It has four parts:

{
  "message": {
    "to": { ... },
    "template": "...",
    "data": { ... },
    "routing": { ... }
  }
}

Part	What it does	Example
`to`	Who gets it: a `user_id` for a stored , or contact details inline	`{ "user_id": "user_123" }`
`template`	What it says: a by its `nt_` ID, or an you assign	`"nt_01kx4h2jdafq8bk9aftxak4b40"`
`data`	The it fills in	`{ "name": "Sarah Bennett" }`
`routing`	Where it goes. Leave it out and the template’s own applies	`{ "method": "single" }`

Pass an array in to to reach several recipients, or contact details inline for a one-off: { "email": "sarah@acme-corp.com" }. A message with no reusable design can carry its content inline instead of a template. That content is , the same format a template renders. Courier enforces each recipient’s at send time. Opt-outs and channel choices apply without extra logic in your code.

The pipeline

The send is asynchronous, so the API responds before delivery happens. Courier records every step, so you can follow a message from request to delivery in . Transient provider errors retry, and an unavailable provider or channel fails over to the next one.

Idempotency

Send an Idempotency-Key header to make a retry safe. A repeated request with the same key returns the original response instead of sending again. A retry after a network failure cannot duplicate the send.

Add routing to pin the channels for this request, or channels and providers to adjust delivery settings. See and .

Limits & behavior

A send is asynchronous. The API returns a requestId, not a delivery result. Track the outcome in the logs or via .
Preferences are enforced automatically. A recipient’s opt-outs and channel choices apply at send time with no extra code.
Idempotency is opt-in. Send an Idempotency-Key header to dedupe retries. Without it, each call sends.

FAQ

Can I send to multiple users at once?

Pass an array of recipients in to, or send to a . For a large group, a list or audience send fans out for you (see ).

Does the API tell me if delivery succeeded?

Not directly. It returns a requestId and the send runs asynchronously. Check delivery in or receive a message:updated .

How do I prevent duplicate sends?

Send an Idempotency-Key header. A second request with the same key returns the original result without sending again.

Get started

Send messages

Journeys

Broadcasts

Design

Recipients

Tenants

Monitoring

Workspaces

Resources

Prerequisites

Three ways to send

1. Templates

Design a Template

2. Broadcasts

Send a Broadcast

3. Journeys

Build a Journey

How it works

The pipeline

Idempotency

Limits & behavior

FAQ

​Prerequisites

​Three ways to send

​1. Templates

Design a Template

​2. Broadcasts

Send a Broadcast

​3. Journeys

Build a Journey

​How it works

​The pipeline

​Idempotency

​Limits & behavior

​FAQ

Prerequisites

Three ways to send

1. Templates

2. Broadcasts

3. Journeys

How it works

The pipeline

Idempotency

Limits & behavior

FAQ