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 Logs to confirm the message rendered and delivered.

Prerequisites

A Courier API key, and the SDK for your language or curl
A template, for the nt_ id in the call above
A saved user, or their contact details inline in to
A connected provider for the channel it goes out on. Test email and the inbox need none.

Three ways to send

All three send the same content: a template 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 variables 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 list or audience, 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 POST /send, 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 profile, or contact details inline	`{ "user_id": "user_123" }`
`template`	What it says: a template by its `nt_` ID, or an alias you assign	`"nt_01kx4h2jdafq8bk9aftxak4b40"`
`data`	The variables it fills in	`{ "name": "Sarah Bennett" }`
`routing`	Where it goes. Leave it out and the template’s own routing 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 Elemental, the same format a template renders. Courier enforces each recipient’s preferences at send time. Opt-outs and channel choices apply without extra logic in your code.

The pipeline

Courier records every step, so you can follow a message from request to delivery in message logs. 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 can’t duplicate the send.

Add routing to pin the channels for this request, or channels and providers to adjust delivery settings. See channel settings & overrides and how routing & failover work.

FAQ

Can I send to multiple users at once?

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

Does the API tell me if delivery succeeded?

The API returns a requestId, not a delivery result, since the send runs asynchronously. Check delivery in message logs or receive a message:updated webhook.

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

In-app

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

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

​FAQ

Prerequisites

Three ways to send

1. Templates

2. Broadcasts

3. Journeys

How it works

The pipeline

Idempotency

FAQ