Message statuses and errors

A send is asynchronous. The API returns a requestId, and the message moves through a status lifecycle you track in the logs.

How it works

The status lifecycle

A message’s status only advances, never backward. Two independent systems drive it. Provider confirmation produces DELIVERED. Courier tracking produces OPENED and CLICKED, so engagement can arrive before or without a delivery confirmation.

Category	Statuses	Meaning
Intermediate	`ENQUEUED`, `ROUTED`, `SENT`	Still processing or awaiting provider confirmation. `SENT` isn’t terminal.
Terminal (delivery)	`DELIVERED`, `UNDELIVERABLE`	Provider accepted, or rejected/failed.
Terminal (engagement)	`OPENED`, `CLICKED`	The recipient interacted.
Terminal (routing)	`UNROUTABLE`, `CANCELED`, `FILTERED`, `UNMAPPED`	The message never reached a provider.
Processing	`DELAYED`, `DIGESTED`, `THROTTLED`	Held for later, batched into a digest, or rate-limited.

Open a message in the to see its provider response.

Send API responses

A successful send returns a requestId you use to track the message:

{ "requestId": "87e7c05b-4f46-fda24e356e23" }

A failed request returns an HTTP error with a message and a type:

Type	Status	Meaning
`invalid_request_error`	400, 404, 409, 413	Malformed request or a missing resource. Fix it before retrying.
`authentication_error`	401	The API key is missing, invalid, or for the wrong environment.
`authorization_error`	403	The key is valid but lacks permission.
`rate_limit_error`	429	A rate limit was exceeded. Back off and retry.
`api_error`	500, 503	A Courier-side error. Retry with exponential backoff.

The most common 400 on /send is Either 'content' or 'template' must be defined. Send one, not both. Next most common are a missing to, or a list_id/audience_id that doesn’t exist. A 413 means the request exceeded the 6 MB payload limit. Host attachments externally and pass URLs in data rather than base64.

Limits

is not rate-limited by request count, so you can send at volume. Its request body caps at 6 MB, as does . Every other endpoint caps at 1 MB. A few management endpoints are rate-limited per workspace. Their responses carry X-RateLimit-Limit and X-RateLimit-Remaining so you can pace requests. Exceeding a limit returns 429 Too Many Requests:

Endpoint	Limit
	60 requests / minute
`POST` or	50 requests / second
	1 request / 2 seconds, per message

Endpoints not listed here aren’t request-count limited today.

Send limits

Send limits cap how many messages a user, topic, or tenant receives in a window. They are a separate feature from API rate limits. A message blocked by one shows as THROTTLED in the log instead of delivering. The Developer plan’s 10,000-sends-per-period cap produces the same THROTTLED status. It applies after the API returns 202, so the status shows up in the message log rather than the response. A THROTTLED message you didn’t set a limit for usually means the plan cap.

Why a message is UNROUTABLE

UNROUTABLE is one status with several causes. Open the message in and read its reason:

`reason`	Cause	Fix
`NO_PROVIDERS`	No provider is configured for the routed channel in this environment, or none of the configured ones is allowed by the send’s channel list.	Configure a provider for the channel in , or drop the channel from `routing`.
`NO_CHANNELS`	No channel resolved for the send.	Add a channel to `routing`, or to the template’s routing strategy.
`UNPUBLISHED`	The template has never been published.	Publish it.
`OPT_IN_REQUIRED`	The topic needs an opt-in the recipient hasn’t given.	See .
`UNSUBSCRIBED`	The recipient opted out of the topic.	Expected. Opt-outs are per tenant, so check the tenant context too.
`FILTERED`	A channel or provider condition evaluated false.	Check the `if` conditions on the channel and provider.

The timeline then shows one attempt per provider, each with its own reason for being skipped:

Provider `reason`	Meaning
`MISSING_CONFIGURATION`	The provider is named on the send or template but isn’t configured in this environment.
`MISSING_PROVIDER_SUPPORT`	The provider doesn’t serve that channel.
`INCOMPLETE_PROFILE_DATA`	The recipient’s profile has no address this provider can use (no `email`, no `phone_number`, no device token).
`FILTERED_AT_PROVIDER`	The provider’s own `if` condition evaluated false.

To audit in bulk, list the failures over the API:

const messages = await client.messages.list({ status: ['UNROUTABLE'] });

for (const message of messages.results) {
  console.log(message.messageId, message.reason);
}

messages = client.messages.list(status=["UNROUTABLE"])

for message in messages.results:
    print(message.message_id, message.reason)

curl "https://api.courier.com/messages?status=UNROUTABLE" \
  -H "Authorization: Bearer $COURIER_API_KEY"

messages = courier.messages.list(status: ["UNROUTABLE"])

messages.results.each do |message|
  puts "#{message.message_id} #{message.reason}"
end

messages, err := client.Messages.List(context.TODO(), courier.MessageListParams{
	Status: []string{"UNROUTABLE"},
})
if err != nil {
	panic(err)
}

for _, message := range messages.Results {
	fmt.Println(message.MessageID, message.Reason)
}

MessageListResponse messages =
    client.messages().list(MessageListParams.builder().addStatus("UNROUTABLE").build());

messages.results().forEach(message ->
    System.out.println(message.messageId() + " " + message.reason()));

$messages = $client->messages->list(status: ['UNROUTABLE']);

foreach ($messages->results as $message) {
  echo $message->messageId . ' ' . $message->reason . PHP_EOL;
}

var messages = await client.Messages.List(new() { Status = ["UNROUTABLE"] });

foreach (var message in messages.Results)
{
    Console.WriteLine($"{message.MessageID} {message.Reason}");
}

courier messages list \
  --api-key "$COURIER_API_KEY" \
  --status UNROUTABLE

With Courier MCP, list my messages with the UNROUTABLE status.

Debug other statuses

Stuck at SENT: delivery tracking isn’t configured for that channel, not a failure. See delivery tracking.
FILTERED: preferences, send conditions, or routing removed the message. Check the recipient’s .
UNDELIVERABLE: the provider rejected it. The timeline shows the provider’s error.

For real-time status without polling, receive the message:updated .

Delivery tracking is per provider

DELIVERED only appears when the provider tells Courier the message landed. That reporting is off until you set it up, per provider. Until then a healthy send stops at SENT. This is the most common reason a working integration looks broken. A provider reports in one of four ways:

How it reports	What you do	Providers
Webhook	Paste Courier’s webhook URL into the provider, and it pushes status in real time.	, , , ,
Polling	Turn the toggle on in the integration’s settings. Courier then asks the provider’s API on a schedule.	SendGrid, Mailgun, , , ,
Immediate	Nothing. The provider acknowledges synchronously, so Courier marks the message `DELIVERED` on accept.	, , , , , ,
Reported by your app	Use a Courier mobile SDK, or `POST` the `trackingUrl` from the payload yourself.

Providers absent from this table send no delivery confirmation, so their messages stop at SENT by design. Where both a webhook and polling are offered, prefer the webhook. It is real time and needs no extra provider permissions.

FAQ

What does UNROUTABLE mean?

Courier found no valid route: the recipient had no address for the routed channel, or no channel was configured for the send. Check the recipient’s profile and the send’s routing.

My message is stuck at SENT. Did it fail?

Usually not. SENT means Courier handed it to the provider and got no delivery confirmation back. That usually means delivery tracking isn’t set up for that channel.

Is the Send API rate-limited?

Not by request count. You can send at volume. A few management endpoints are limited (see the table above). Send limits (per user, topic, or tenant) govern message volume and mark blocked messages THROTTLED.

Why did I get a 413?

The request exceeded the body-size cap: 6 MB on /send and /automations/invoke, 1 MB on every other endpoint. Host attachments externally and pass their URLs in data. Base64 inflates size by about a third.

Get started

Send messages

Journeys

Broadcasts

Design

In-app

Recipients

Tenants

Monitoring

Workspaces

Resources

Message statuses and errors

How it works

The status lifecycle

Send API responses

Limits

Send limits

Why a message is UNROUTABLE

Debug other statuses

Delivery tracking is per provider

FAQ

​How it works

​The status lifecycle

​Send API responses

​Limits

​Send limits

​Why a message is UNROUTABLE

​Debug other statuses

​Delivery tracking is per provider

​FAQ

How it works

The status lifecycle

Send API responses

Limits

Send limits

Why a message is UNROUTABLE

Debug other statuses

Delivery tracking is per provider

FAQ