Understand Message Statuses
Every message in Courier progresses through a series of statuses. The most important distinction for email troubleshooting is the difference between Sent and Delivered.| Status | What it means | What it does NOT mean |
|---|---|---|
| Sent | Courier handed the message to your email provider and the provider accepted it. | The email reached the recipient’s inbox. A 200 from the provider is an acknowledgment, not a delivery guarantee. |
| Delivered | The provider confirmed the recipient’s mail server accepted the message. | The email is in the recipient’s inbox. The mail server may still filter or quarantine it internally. |
| Undeliverable | The provider reported a hard failure: bounce, block, or suppression. | Nothing further will happen; Courier will not retry. |
| Filtered | Courier filtered the message before sending, due to preferences, send conditions, or routing rules. | The message was never sent to a provider. |
Debug with Message Logs
Find the message
Open Message Logs and filter by recipient email address, notification template, or date range. Click the message to open the detail view.
Read the timeline
The timeline shows every step from request to delivery. Look for where the message stopped progressing:
- Request Received → Courier accepted the API call
- Event Mapped → The notification template was resolved
- Routed → Channel routing completed
- Rendered → Content was generated for the provider
- Sent → Provider accepted the message
- Delivered → Provider confirmed mail server acceptance
Common Scenarios
Message stuck at “Sent”
The provider accepted the message but hasn’t reported a delivery outcome yet. Possible causes:- Polling delay. For providers that use polling-based delivery tracking (SendGrid, Postmark, Mailgun), Courier checks the provider’s API periodically. Status updates can take a few minutes.
- Missing delivery tracking config. AWS SES requires SNS webhook setup to report delivery status back to Courier. Without it, messages stay at “Sent” indefinitely.
- Deferred delivery. The recipient’s mail server accepted the message but deferred final delivery. The provider may still be retrying.
- Wait 15-30 minutes; polling-based providers need time to report status
- Check your provider’s dashboard for the message status (SendGrid Activity Feed, Postmark Activity, etc.)
- If you use AWS SES, verify that SNS delivery tracking is configured
Message shows “Undeliverable”
The provider reported a hard failure. Possible causes:- Hard bounce. The email address doesn’t exist or the domain is invalid.
- Soft bounce. The recipient’s mailbox is full or temporarily unavailable. Some providers retry automatically before reporting failure.
- Block. The recipient’s mail server or provider blocked the message based on sender reputation, content, or policy.
- Suppression list. The email address is on the provider’s suppression list from a previous bounce or spam complaint. Check your provider’s suppression list management.
- Click the Undeliverable event in the timeline to see the provider’s error message
- Check your provider’s dashboard for bounce details and suppression list entries
- If the address is valid, verify your sender authentication (see Sender Authentication Checklist)
Message shows “Delivered” but recipient didn’t get it
The email reached the recipient’s mail server but isn’t in their inbox. Possible causes:- Spam folder. The email was flagged by the recipient’s email client. Ask the recipient to check their spam/junk folder.
- Enterprise email security. Organizations often run email security gateways (Proofpoint, Mimecast, Barracuda) that silently quarantine messages after the mail server accepts them. This is common with corporate email domains.
- Inbox rules. The recipient may have filters or rules that moved the message to a folder or deleted it automatically.
- Confirm the recipient checked their spam/junk folder
- If all affected recipients share the same domain (e.g.,
@company.com), it’s likely a domain-level email security filter. The recipient’s IT team needs to check their email security quarantine and allowlist your sending domain. - Try sending a test email to a personal/non-corporate address as a control test
Message shows “Filtered”
Courier filtered the message before it reached a provider. Possible causes:- User preferences. The recipient opted out of this notification type or channel via Preferences.
- Send conditions. The notification template has send conditions that evaluated to false.
- Routing rules. No valid channel was found for the recipient (e.g., missing email address on their profile).
- Check the filter reason in the message timeline
- Review the recipient’s user profile for missing contact info
- Check the template’s send conditions and the recipient’s notification preferences
Provider-Specific Troubleshooting
Each provider has its own dashboard and tools for investigating delivery issues. After identifying the problem in Courier’s message logs, use these provider-specific resources to dig deeper:- SendGrid: Check the Activity Feed for per-message delivery events. Enable Email Activity Tracking in your SendGrid integration for polling-based status updates.
- Postmark: Use the Activity dashboard to see delivery, bounce, and spam complaint details per message.
- AWS SES: Check the SES console under Reputation Dashboard for bounce and complaint rates. Make sure SNS delivery tracking is configured; without it, Courier can’t track delivery status.
- Mailgun: Use the Logs dashboard for per-message event history including delivery, bounce, and complaint events.
- Mandrill: Check the Outbound Activity for message status and bounce details.
Sender Authentication Checklist
Poor sender authentication is one of the most common causes of delivery issues. Verify the following for your sending domain:| Record | Purpose | How to check |
|---|---|---|
| SPF | Authorizes which mail servers can send on behalf of your domain | Look up your domain’s TXT records for an v=spf1 entry that includes your provider |
| DKIM | Cryptographically signs emails to prove they haven’t been tampered with | Your provider’s dashboard will show DKIM status; look for a CNAME or TXT record |
| DMARC | Tells receiving servers how to handle emails that fail SPF or DKIM checks | Look up _dmarc.yourdomain.com for a TXT record; start with p=none to monitor |