Email Events

Every email sent through RelayPost generates a trail of events as it moves through the delivery pipeline. You can query these events via the API or receive them in real time via webhooks.

Query events for an email

GET /api/v1/emails/:id

The response includes the full event timeline for the email.

curl "https://relaypost.dev/api/v1/emails/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "message_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "from_address": "[email protected]",
    "to_addresses": ["[email protected]"],
    "subject": "Your receipt",
    "status": "delivered",
    "events": [
      {
        "id": "evt_001",
        "type": "delivered",
        "recipient": "[email protected]",
        "smtp_code": 250,
        "smtp_message": "OK",
        "created_at": "2025-01-15T10:30:05.000Z"
      }
    ]
  }
}

Event types

Type	Description
`queued`	Email accepted into the delivery queue
`processing`	Delivery attempt in progress
`delivered`	Successfully accepted by the recipient’s mail server
`opened`	Recipient opened the email (pixel tracking)
`bounced`	Recipient’s server permanently rejected the email
`deferred`	Temporary failure — will retry automatically
`failed`	All retry attempts exhausted
`complained`	Recipient reported the email as spam
`rejected`	Email rejected before sending (validation, suppression)

Event fields

Field	Type	Description
`type`	String	Event type (see above)
`recipient`	String	The recipient email address
`mx_host`	String	The MX server that handled the email
`smtp_code`	Int	SMTP response code (e.g., 250, 550)
`smtp_message`	String	SMTP response message from the receiving server
`created_at`	DateTime	When the event occurred

Common SMTP codes

Code	Meaning
`250`	Success — email accepted
`421`	Service temporarily unavailable — will retry
`450`	Mailbox temporarily unavailable — will retry
`550`	Mailbox not found — hard bounce
`551`	User not local — forwarding error
`552`	Mailbox full
`553`	Invalid mailbox name
`554`	Transaction failed — often a policy rejection

Dashboard

You can also view events in the RelayPost dashboard under Messages. Click any email to see its full event timeline.