Track delivery

Every email you send leaves a timeline. Read a send’s current status with the id the send call returned, page its per-recipient delivery events, or have the same signals pushed to your app as they happen.

The lifecycle

A send’s status tells you where it stands right now:

Status	Meaning
`scheduled`	Accepted with a future `sendAt`; waiting to fire.
`queued`	Waiting for delivery — the state a broadcast’s per-recipient sends pass through. An immediate single send never returns `queued`.
`sent`	The message left Dairo. Confirmation from the recipient’s mail server arrives as a `Delivery` event.
`bounced`	A terminal negative signal landed — a bounce stamps `bouncedAt`, a spam complaint stamps `complainedAt`.
`failed`	The send could not be completed; `error` carries the reason. Includes a scheduled send that failed its fire-time re-check.
`canceled`	A scheduled send you canceled before it fired.

Delivery confirmations do not change status — they are recorded as events and advance the send’s lastEventType and lastEventAt fields, so a sent message with lastEventType: "Delivery" has been accepted by the recipient’s mail server.

Read a send

Fetch a send with GET /v1/messages/{messageId} (scope messages:read), using the id returned when you sent it.

curl https://api.dairo.app/v1/messages/msg_3fa85f64 \
  -H "Authorization: Bearer $DAIRO_API_KEY"

const message = await dairo.messages.get("msg_3fa85f64");
console.log(message.status, message.lastEventType);

message = dairo.messages.get("msg_3fa85f64")
print(message.status)

dairo outbound get msg_3fa85f64

{
  "object": "message",
  "id": "msg_3fa85f64",
  "inboxId": "inbox_7c9e6679",
  "channel": "email",
  "from": "receipts@yourapp.com",
  "to": ["nobody@example.com"],
  "subject": "Your receipt",
  "status": "bounced",
  "sentAt": "2026-06-12T11:59:58Z",
  "providerMessageId": "msg_pm_9f8c2a1b4e7d",
  "lastEventType": "Bounce",
  "lastEventAt": "2026-06-12T12:00:00Z",
  "bouncedAt": "2026-06-12T12:00:00Z",
  "complainedAt": null,
  "createdAt": "2026-06-12T11:59:57Z"
}

Page the delivery events

For the full timeline, list one send’s delivery events with GET /v1/messages/{messageId}/events — newest first, default 50, up to 100 per request.

curl "https://api.dairo.app/v1/messages/msg_3fa85f64/events?limit=50" \
  -H "Authorization: Bearer $DAIRO_API_KEY"

const { events } = await dairo.messages.listEvents("msg_3fa85f64", { limit: 50 });

// Convenience filters over the same timeline:
const bounces = await dairo.messages.listBounces("msg_3fa85f64");
const complaints = await dairo.messages.listComplaints("msg_3fa85f64");

events = dairo.messages.list_events("msg_3fa85f64", limit=50)
bounces = dairo.messages.list_bounces("msg_3fa85f64")

dairo outbound events --email-id msg_3fa85f64

{
  "events": [
    { "eventId": "evt_9d2b", "messageId": "msg_3fa85f64", "type": "Bounce", "recipient": "nobody@example.com", "bounceType": "Permanent", "occurredAt": "2026-06-12T12:00:00Z" },
    { "eventId": "evt_5c1a", "messageId": "msg_3fa85f64", "type": "Send", "occurredAt": "2026-06-12T11:59:58Z" }
  ]
}

Event fields

Each event says what happened, to whom, and when.

Field	Meaning
`type`	The delivery event: `Send`, `Delivery`, `DeliveryDelay`, `Bounce`, `Complaint`, `Reject`, or `Rendering Failure`.
`recipient`	The affected address.
`occurredAt`	When the event happened at the recipient’s mail server.
`bounceType`	`Permanent`, `Transient`, or `Undetermined`.
`bounceSubType`	A finer classification, e.g. `General` or `MailboxFull`.
`diagnosticCode`	The reason the receiving mail server gave for a bounce.
`complaintFeedbackType`	The kind of complaint, e.g. `abuse` or `fraud`.
`agentHint`	On bounce and complaint events, a short machine-readable recommendation for what to do next.

Events can arrive out of order. Sort by occurredAt — not by when you received each event — when you reconstruct a message’s lifecycle.

What to do with each signal

Signal	What it means	What to do
`Bounce` with `bounceType: "Permanent"`	The address doesn’t exist or refuses mail.	Take it off your lists and don’t retry — repeated hard bounces hurt your reputation and push future mail toward spam.
`Bounce` with `bounceType: "Transient"`	A full mailbox or a temporary server problem.	Back off and retry later rather than giving up right away.
`Complaint`	The recipient marked your mail as spam — the strongest negative signal there is.	Stop contacting them. Dairo blocks future sends to that address for you.

Get events pushed to you

Polling works, but for real-time updates subscribe to message.delivered, message.bounced, and message.complained via webhooks, and Dairo calls your app the moment each one lands. For a single, durable, account-wide stream of everything, read the event ledger.

Next steps

Land in the inbox — cut bounces and complaints at the source.
Audiences & broadcasts — track a fan-out per recipient.
API reference — every messages endpoint, with copy-paste requests.

Get started

Sending

Channels

Contacts

Files & storage

Send physical mail

Phone

Receiving

Domains & deliverability

Events & webhooks

Guides

Foundations

For AI agents

Scale & compliance

The lifecycle

Read a send

Page the delivery events

Event fields

What to do with each signal

Get events pushed to you

Next steps

​The lifecycle

​Read a send

​Page the delivery events

​Event fields

​What to do with each signal

​Get events pushed to you

​Next steps

The lifecycle

Read a send

Page the delivery events

Event fields

What to do with each signal

Get events pushed to you

Next steps