Email Events

What Are Email Delivery Events?

Email delivery events are status notifications generated at each stage of the email delivery pipeline — from initial queue acceptance through final delivery, bounce, or failure. Tracking these events gives senders real-time visibility into whether each email reached the recipient’s inbox, bounced, or was marked as spam.

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://api.relaypost.dev/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": "hello@yourdomain.com",
    "to_addresses": ["user@example.com"],
    "subject": "Your receipt",
    "status": "delivered",
    "events": [
      {
        "id": "evt_001",
        "type": "delivered",
        "recipient": "user@example.com",
        "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.

Frequently Asked Questions

What email events does RelayPost track?

RelayPost tracks these events: queued, processing, delivered, opened, bounced, deferred, failed, complained, and rejected. Each event includes the recipient, timestamp, SMTP code, and server response.

How do I get real-time email events?

Set up a webhook endpoint to receive HTTP POST notifications as events occur. Alternatively, query the API to get the full event timeline for any email by its ID.

What does the “deferred” event mean?

A deferred event means the recipient’s mail server returned a temporary failure (SMTP 4xx code). RelayPost automatically retries deferred emails with exponential backoff. If all retries fail, a “failed” event is generated.