Handle bounces & interpret statuses
Read the delivery timeline and act on BOUNCED, FAILED, DEFERRED.
Read the delivery timeline, tell temporary problems apart from permanent ones, and stop sending to addresses that will never accept mail.
Prerequisite: Send your first transactional email. Track results with callbacks (Receive delivery callbacks) or by polling the tracking API.
1. Read the delivery timeline
Every message moves through a lifecycle. Each event carries a machine deliveryStatus and a human-readable status.
Fetch the timeline for one message:
curl -X GET 'https://connect.routee.net/email/tracking/single/TRACKING_ID' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'Or search across messages with filters (date range, status, recipient):
curl -X POST 'https://connect.routee.net/email/tracking?page=0&size=20' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-d '{ "status": "BOUNCED" }'
Rows appear about 1–2 minutes after send. See Search email tracking and Get email tracking (single message timeline) for all filters and fields.
2. Lifecycle events
| Event | Meaning | Final? |
|---|---|---|
QUEUED | Accepted and waiting to send | No |
SENT | Handed to the receiving mail server | No |
DELIVERED | Accepted by the recipient's mailbox | Yes |
DEFERRED | Temporary problem; Routee may retry | No |
BOUNCED | Permanent failure (for example, unknown mailbox) | Yes |
FAILED | Undeliverable after retries were exhausted | Yes |
3. Distinguish temporary from permanent
| Signal | What it means | What to do |
|---|---|---|
DEFERRED | Greylisting, throttling, or a full mailbox — often clears on its own | Let Routee's retries run; don't resend manually |
BOUNCED | The address is invalid or the mailbox rejects permanently | Suppress the address immediately |
FAILED | Delivery gave up after retries | Investigate the reason, then suppress or fix |
Tune retry behaviour on the send payload:
{
"ttl": 60,
"maxAttempts": 3,
"dsn": { "notify": "FAILURE,DELAY" }
}ttl— minutes Routee keeps trying before giving up.maxAttempts— number of delivery attempts.dsn.notify— comma-separatedFAILURE,DELAY,SUCCESS,NEVER.
See DSN object explained.
4. Maintain a suppression list
Protect your sender reputation by never re-sending to permanently failing addresses.
- On
BOUNCED(and confirmedFAILED), add the recipient to a suppression list. - Check that list before every send and skip suppressed addresses.
- Keep it durable — bounces you ignore hurt deliverability for everyone on your domain.
5. Common 400 rejections
Some sends never enter the lifecycle because they're rejected at the API with a 400 and an error code:
| Code | Meaning |
|---|---|
000000 | Invalid domain |
000001 | Invalid sender |
000002 | Unverified sender |
000003 | Message exceeds size limit |
000004 | No active subscription |
000005 | Insufficient subscription resources |
Full list: Email error codes.
Next steps
- Build & secure a webhook receiver — get status changes pushed to you
- Deliverability checklist — reduce bounces before they happen
- Email tracking, statuses & callbacks — full lifecycle reference