Debug email delivery

A recipient says the email never arrived. Start in Logs and work outward, from Courier to the provider to the inbox.

Prerequisites

A message you can point to, or the recipient and roughly when you sent it.
Access to your email provider’s dashboard, for everything past the handoff.

Read the status first

The status tells you which half of the trip failed. covers the full lifecycle. Two of them cause most of the confusion:

SENT means the provider accepted the message. It isn’t a delivery confirmation.
DELIVERED means the recipient’s mail server accepted it. It isn’t proof the message reached the inbox.

A corporate mail gateway (Proofpoint, Mimecast, Barracuda) can quarantine a message after the server accepts it. DELIVERED with an empty inbox usually means the message is held on the recipient’s side.

Find where it stopped

Open the message

Filter by recipient, template, or time range, then open the message.

Read the timeline

The timeline lists every step the message passed, from the request through routing, rendering, and the provider handoff. The last step that succeeded tells you who owns the problem.

Open the provider response

Select the send event to see what the provider returned, including its status code and its own message id. Use that id to find the same message in the provider’s dashboard.

See exactly what was rendered

The timeline tells you where a message stopped. It doesn’t tell you what the recipient actually got, which is the question behind most “the notification looked wrong” reports. returns the rendered content Courier delivered, broken out per channel:

const { results } = await client.messages.content("1-61e9e2f0-1f8b0d5e");

for (const output of results) {
  console.log(output.channel, output.content.subject);
}

response = client.messages.content("1-61e9e2f0-1f8b0d5e")

for output in response.results:
    print(output.channel, output.content.subject)

curl "https://api.courier.com/messages/1-61e9e2f0-1f8b0d5e/output" \
  -H "Authorization: Bearer $COURIER_API_KEY"

response = courier.messages.content("1-61e9e2f0-1f8b0d5e")

response.results.each do |output|
  puts("#{output.channel} #{output.content.subject}")
end

response, err := client.Messages.Content(context.TODO(), "1-61e9e2f0-1f8b0d5e")
if err != nil {
	panic(err.Error())
}

for _, output := range response.Results {
	fmt.Println(output.Channel, output.Content.Subject)
}

MessageContentResponse response = client.messages().content("1-61e9e2f0-1f8b0d5e");

response.results().forEach(output ->
    System.out.println(output.channel() + " " + output.content().subject()));

$response = $client->messages->content('1-61e9e2f0-1f8b0d5e');

foreach ($response->results as $output) {
    echo $output->channel, ' ', $output->content->subject, PHP_EOL;
}

var response = await client.Messages.Content("1-61e9e2f0-1f8b0d5e", new());

foreach (var output in response.Results)
{
    Console.WriteLine($"{output.Channel} {output.Content.Subject}");
}

courier messages content 1-61e9e2f0-1f8b0d5e \
  --api-key "$COURIER_API_KEY"

With Courier MCP, show me the rendered content for message 1-61e9e2f0-1f8b0d5e.

Each result carries the channel it was rendered for and a content object holding whichever fields that channel uses, such as subject and html for email or text for SMS:

{
  "results": [
    {
      "channel": "email",
      "channel_id": "abc-123",
      "content": {
        "subject": "Your report is ready",
        "title": "Your report is ready",
        "html": "<html>…</html>",
        "text": "Your report is ready…"
      }
    }
  ]
}

This is what separates the three explanations that all look the same from the outside:

What you see	What it means
A variable rendered as an empty string	The template is fine and `data` was missing a key
The variable name rendered literally	The template references a variable that doesn’t exist
Content correct, provider rejected it	Neither one. Take the payload to the provider

For the ordered list of status transitions and their timestamps, use .

Work the scenario

Stuck at SENT

Usually not a failure. Delivery confirmation is off until you configure it, per provider, so a healthy send stops at SENT. Check and set up its webhook or polling toggle.If tracking is already configured, the provider may be retrying a deferral, or Courier may not have polled yet. Confirm the outcome in the provider’s dashboard.

UNDELIVERABLE

The provider rejected the message, and Courier doesn’t retry. Open the event for the provider’s error, then match it to a cause:

Hard bounce. The address doesn’t exist, or the domain doesn’t resolve.
Soft bounce. The mailbox is full or temporarily unavailable. Some providers retry before reporting failure.
Block. The receiving server refused the message on reputation, content, or policy.
Suppression. The address sits on the provider’s suppression list from an earlier bounce or complaint. Remove it there before you can send to that address again.

A valid address that bounces on reputation points at sender authentication.

DELIVERED, but not in the inbox

The message reached the mail server. Three things commonly take it from there:

Spam or junk. Ask the recipient to check both folders.
A security gateway. When every affected recipient shares one domain, their IT team has to check the quarantine and allowlist your sending domain.
An inbox rule. A filter the recipient set may have moved or deleted the message.

Send the same template to a personal address as a control. If that copy arrives, the problem is the recipient’s domain, not your send.

FILTERED or UNROUTABLE

The cause is inside Courier: the message stopped before it reached a provider. FILTERED means preferences, a send condition, or a channel condition removed it. UNROUTABLE means no channel could be addressed, usually a missing email address on the profile. lists each reason and its fix.

Check sender authentication

Weak authentication causes failures that look random and hit many recipients at once. Confirm all three records for your sending domain:

Record	What it does	How to check
SPF	Names the servers allowed to send for your domain	Look for a `v=spf1` TXT record that includes your provider
DKIM	Signs the message so the receiver can prove nothing altered it	Your provider’s dashboard shows DKIM status and the record to add
DMARC	Tells receivers what to do when SPF or DKIM fails	Look for a TXT record at `_dmarc.yourdomain.com`, starting at `p=none` to monitor

Each provider’s setup page walks through its own records. See the .

Tracked links use a shared ct0.app domain by default. A puts them on your own domain, which some filters treat more kindly. It is available on Business and above.

Ask the provider

Courier’s logs end where the provider takes over, so the delivery event itself lives there:

SendGrid: the Activity Feed, per-message delivery events.
Postmark: Activity, with bounce and complaint detail.
AWS SES: the Reputation Dashboard, for bounce and complaint rates.
Mailgun: Logs, for a message’s full event history.
Mandrill: Outbound Activity.

Debug from an AI agent

exposes the same message data as the console, so you can ask instead of click:

What you want	Tool
Find the message	`list_messages`
Read its status and provider	`get_message`
Walk the timeline	`get_message_history`
See what was actually sent	`get_message_content`
Check the recipient’s contact info	`get_user_profile_by_id`
Check their preferences	`get_user_preferences`

MCP

With Courier MCP, show me every undeliverable message from the last 24 hours and what each provider said.

An agent chains these, so one prompt can check a profile, confirm preferences, find the message, and read its timeline. The covers the same ground in a script.

Verify

Send the template to a test recipient and watch the status pass SENT in Logs. After a suppression or authentication fix, confirm the provider’s own dashboard shows the new message as delivered.

Get started

Send your first message

Build a notification

Send to many people

Send when something happens

Let users choose

Go live

Move to Courier

Debug email delivery

Prerequisites

Read the status first

Find where it stopped

See exactly what was rendered

Work the scenario

Check sender authentication

Ask the provider

Debug from an AI agent

Verify

​Prerequisites

​Read the status first

​Find where it stopped

​See exactly what was rendered

​Work the scenario

​Check sender authentication

​Ask the provider

​Debug from an AI agent

​Verify

Prerequisites

Read the status first

Find where it stopped

See exactly what was rendered

Work the scenario

Check sender authentication

Ask the provider

Debug from an AI agent

Verify