<Intro>

<EndpointHeader />

<Description>

Returns the message's per-recipient delivery state as a cursor page: each entry is one `to`/`cc`/`bcc` recipient with its role, current `status`, rejection or bounce detail when delivery failed, and open/click counts. Use it to see which specific addresses failed when the aggregate message `status` is mixed (for example `partial_failure`).

</Description>

</Intro>

<Parameters in="path">

<Parameter name="message_id" type="string">

<Description>

ID of the message whose recipients to list, from the send response's `id` field (`em_`-prefixed).

</Description>

</Parameter>

</Parameters>

<Parameters in="query">

<Parameter name="limit" type="integer">

<Description>

Maximum number of items to return per page.

</Description>

</Parameter>

<Parameter name="starting_after" type="string">

<Description>

Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order.

</Description>

</Parameter>

<Parameter name="ending_before" type="string">

<Description>

Cursor from the `prev_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order.

</Description>

</Parameter>

</Parameters>

<Payload kind="response">

<Field name="data" type="array of object" required>

<Description>

Page of recipient objects for this email send.

</Description>

<FieldChildren kind="response">

<Field name="id" type="string" prefix="data." required>

<Description>

Recipient ID.

</Description>

</Field>

<Field name="parent_id" type="string" prefix="data." required>

<Description>

ID of the parent message (em_ prefix) or broadcast (eb_ prefix) this recipient belongs to.

</Description>

</Field>

<Field name="role" type="string" prefix="data." required>

<Description>

How this recipient appeared in the send request.

</Description>

<Description>

Possible values: `to`, `cc`, `bcc`

</Description>

</Field>

<Field name="recipient" type="string" prefix="data." required>

<Description>

Recipient email address.

</Description>

</Field>

<Field name="name" type="nullable string" prefix="data.">

<Description>

Display name provided for this recipient on the send, or null if none was given.

</Description>

</Field>

<Field name="status" type="string" prefix="data." required>

<Description>

Delivery status for this recipient. `accepted` means Bird has the send and is
preparing to deliver; `processed` means the message was handed to the delivery
pipeline for this recipient; `deferred` means the recipient's mailbox provider
asked Bird to retry and delivery attempts continue; `delivered` means the
recipient's mail server accepted the message; `bounced` means delivery permanently
failed (see `bounce_type` for hard vs soft); `complained` means the recipient
reported the message as spam; `rejected` means Bird did not attempt delivery (see
`rejection_reason` for why).

</Description>

<Description>

Possible values: `accepted`, `processed`, `deferred`, `delivered`, `bounced`, `complained`, `rejected`

</Description>

</Field>

<Field name="rejection_reason" type="nullable string" prefix="data.">

<Description>

Present on `status: rejected` rows. Specifies why the recipient was rejected:

- `recipient_suppressed`: the recipient is on the workspace suppression list. Bird
  did not attempt delivery.
- `transmission_failed`: the message could not be transmitted for delivery.
- `generation_failure`: the message could not be built for delivery (template or
  content issue).
- `policy_rejection`: the message was refused by sending policy.
- `domain_unverified`: the sending domain was not verified.
- `quota_exceeded`: the organization's send quota was reached.
- `recipient_not_allowed`: a recipient was not permitted for this send (for shared
  onboarding-domain sends, recipients must be verified workspace members).

</Description>

<Description>

Possible values: `recipient_suppressed`, `transmission_failed`, `generation_failure`, `policy_rejection`, `domain_unverified`, `quota_exceeded`, `recipient_not_allowed`, `null`

</Description>

</Field>

<Field name="bounce_type" type="nullable string" prefix="data.">

<Description>

Bounce classification for `bounced` and `deferred` rows, or null when the recipient has not bounced or the receiving server's response has not been classified. `hard` is a permanent failure (invalid address or non-existent domain). `soft` is a transient failure (mailbox full, server temporarily unavailable). `block` indicates the receiving mail server blocked the sending IP for reputation reasons. `admin` indicates an administrative refusal (relaying denied, blocklisted domain). `undetermined` is used when the receiving server's response is ambiguous.

</Description>

<Description>

Possible values: `hard`, `soft`, `undetermined`, `admin`, `block`, `null`

</Description>

</Field>

<Field name="bounce_code" type="nullable string" prefix="data.">

<Description>

SMTP reply code returned by the receiving mail server for `bounced` and `deferred` rows, or null when none was provided.

</Description>

</Field>

<Field name="bounce_description" type="nullable string" prefix="data.">

<Description>

Human-readable reason the receiving mail server gave for the bounce or deferral, or null when none was provided.

</Description>

</Field>

<Field name="processed_at" type="nullable string" prefix="data.">

<Description>

When Bird processed the message and queued it for delivery to the recipient's mail server, or null if not yet processed.

</Description>

</Field>

<Field name="delivered_at" type="nullable string" prefix="data.">

<Description>

When the recipient's mail server accepted the message, or null if not yet delivered.

</Description>

</Field>

<Field name="processing_latency_ms" type="nullable integer" prefix="data.">

<Description>

Time between Bird accepting the send and processing the message for delivery, in milliseconds. Null until processed.

</Description>

</Field>

<Field name="delivery_latency_ms" type="nullable integer" prefix="data.">

<Description>

Time between Bird processing the message and the receiving mail server accepting it, in milliseconds. Null until delivered.

</Description>

</Field>

<Field name="total_latency_ms" type="nullable integer" prefix="data.">

<Description>

End-to-end accept → delivered time for this recipient, in milliseconds. Null until delivered.

</Description>

</Field>

<Field name="open_count" type="integer" prefix="data." required>

<Description>

Number of open events for this recipient.

</Description>

</Field>

<Field name="click_count" type="integer" prefix="data." required>

<Description>

Number of click events for this recipient.

</Description>

</Field>

</FieldChildren>

</Field>

<Field name="next_cursor" type="nullable string" required>

<Description>

Cursor for the next page. Pass back as `starting_after` to advance forward. Null when no next page exists.

</Description>

</Field>

<Field name="prev_cursor" type="nullable string" required>

<Description>

Cursor for the previous page. Pass back as `ending_before` to step backward. Null when no previous page exists.

</Description>

</Field>

<Field name="refresh_cursor" type="nullable string" required>

<Description>

Refresh anchor. Pass back as `ending_before` later to fetch items that have appeared since this response. Non-null whenever `data` is non-empty; null only on an empty page. Distinct from `prev_cursor`.

</Description>

</Field>

</Payload>