Get email status

Check whether a sent email has been queued, delivered, bounced, or rejected.

GET

/api/v1/partner/email/emails/:message_id

Path parameters

Field	Notes
`message_id`	UUID returned from `/send` / `/send-template` / `/send-bulk` / `/send-raw`

Response

{
  "success": true,
  "message_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "delivered",
  "from_address": "[email protected]",
  "to_address": "[email protected]",
  "subject": "Welcome",
  "category": "transactional",
  "smtp_message_id": "<[email protected]>",
  "created_at": "2026-05-03T12:34:56Z",
  "sent_at": "2026-05-03T12:34:57Z",
  "delivered_at": "2026-05-03T12:34:57Z"
}

Status values

Status	Meaning
`queued`	API accepted; not yet delivered to recipient MX
`sent`	Sent to recipient MX (collapsed with `delivered` for our pipeline)
`delivered`	Recipient MX returned 250 OK
`bounced`	Hard or soft-bounce-exhausted bounce
`complained`	Recipient marked as spam (FBL report received)
`rejected`	Refused pre-SMTP (suppression list, sandbox cap, etc.)
`failed`	Soft bounce retries exhausted

Bounce details

When status: bounced:

{
  "status": "bounced",
  "bounced_at": "2026-05-03T12:35:01Z",
  "bounce_type": "Permanent",
  "bounce_reason": "no_such_user"
}

When to use polling vs webhooks

Polling is the wrong default. Webhooks (set up via event destinations) push status changes to your server within seconds without you polling.

Use this endpoint for:

One-off lookups (debugging a specific send)
UI surfaces showing live status (after a webhook update lands)
Reconciliation jobs (check that webhook delivery wasn't dropped)

Don't poll every send every 5 seconds — wasteful for both sides.

Common errors

Status	Code	Meaning
404	`MESSAGE_NOT_FOUND`	Message id doesn't match any send. Possible: wrong account, malformed id, or message older than retention window

Retention

Outbox rows are retained for 30 days. After that, older rows return 404. For long-term audit, listen to the Send / Delivery / Bounce webhook events and persist them yourself.