Sign inGet Started
Jetzt starten
Anleitungen
API-Referenz
SDKs
CLI
Wissensdatenbank
Changelog

List recipients of a message

GET
/v1/email/messages/{message_id}/recipients
bird email recipients <message-id>
Antwort200
{
  "data": [
    {
      "id": "er_01krdgeqcxet5s7t44vh8rt9mg",
      "parent_id": "em_01krdgeqcxet5s7t44vh8rt9mg",
      "role": "to",
      "recipient": "delivered@messagebird.dev",
      "status": "accepted",
      "rejection_reason": "recipient_suppressed",
      "bounce_type": "hard",
      "bounce_code": "550",
      "bounce_description": "5.1.1 Unknown user",
      "open_count": 0,
      "click_count": 0
    }
  ],
  "next": [
    {
      "kind": "operation"
    }
  ],
  "next_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE0OjAzOjEwWlwiIiwiaSI6IjAxOTJmM2IxLTRjN2UtN2EyYi05ZDYxLThmM2E1YzJlN2I0MCJ9",
  "prev_cursor": null,
  "refresh_cursor": "eyJ2IjoxLCJzIjoiXCIyMDI2LTA1LTI1VDE2OjQyOjAxWlwiIiwiaSI6IjAxOTJmM2IxLTllMDQtN2NkMy1iODE3LTJhNmY0ZDFjOGUwOSJ9"
}

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).

This works for every email message, including one a broadcast sent. A broadcast records one message per recipient, so such a message has exactly one recipient here: the address its copy went to.

Parameter

message_idstring

ID of the message whose recipients to list. A broadcast records one message per recipient, and List email messages returns those copies alongside ordinary sends. For a single send, this is the message's own ID, from the send response's id field.

Abfrageparameter

limitinteger

Maximum number of items to return per page.

starting_afterstring

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

ending_beforestring

Cursor from the prev_cursor or refresh_cursor field of a previous list response. Returns items immediately before the cursor position in the current sort order. prev_cursor returns the preceding page. refresh_cursor anchors at the first row of that response, which on a newest-first sort is how to fetch the items that have appeared since.

Antwort-Payload

data
array of object
erforderlich

Page of recipient objects for this email send.

Untergeordnete Attribute anzeigen
data.id
string
erforderlich

Recipient ID.

data.parent_id
string
erforderlich

ID of the message this recipient belongs to. For a message send, this is the message's own em_-prefixed ID. For a broadcast, it is the em_-prefixed ID of the copy addressed to this recipient. Read either one with Get an email message, which answers 404 for a broadcast copy the send has not recorded. No recipient status distinguishes a copy the send recorded from one it did not.

data.role
string
erforderlich

How this recipient appeared in the send request.

Possible values: to, cc, bcc

data.recipient
string
erforderlich

Recipient email address.

data.name
nullable string

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

data.status
string
erforderlich

Delivery status for this recipient:

  • accepted: The send has been taken and is being prepared for delivery.
  • processed: This recipient's message is on its way out.
  • deferred: The recipient's mailbox provider asked for a retry, and delivery attempts continue.
  • delivered: The recipient's mail server accepted the message.
  • bounced: Delivery permanently failed (see bounce_type for hard vs soft).
  • complained: The recipient reported the message as spam.
  • rejected: Delivery was never attempted (see rejection_reason for why).

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

data.rejection_reason
nullable string

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

  • recipient_suppressed: The recipient is on the workspace suppression list, so delivery was never attempted.
  • 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).

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

data.bounce_type
nullable string

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: a permanent failure (invalid address or non-existent domain).
  • soft: a transient failure (mailbox full or server temporarily unavailable).
  • block: the receiving mail server blocked the sending IP for reputation reasons.
  • admin: an administrative refusal (relaying denied or blocklisted domain).
  • undetermined: the receiving server's response is ambiguous.

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

data.bounce_code
nullable string

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

data.bounce_description
nullable string

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

data.processed_at
nullable string

When the message was prepared and queued for delivery to the recipient's mail server, or null if that has not happened yet.

data.delivered_at
nullable string

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

data.processing_latency_ms
nullable integer

Time between the send being accepted and the message being prepared for delivery, in milliseconds. Null until processed.

data.delivery_latency_ms
nullable integer

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

data.total_latency_ms
nullable integer

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

data.open_count
integer
erforderlich

Number of open events for this recipient.

data.click_count
integer
erforderlich

Number of click events for this recipient.

next
array of object

What to do next, given what this page reports. Present only where the read computes it: an empty list means the answer you were looking for is here and there is nothing further to do. Absent entirely on reads that do not report next actions.

Untergeordnete Attribute anzeigen
next_cursor
nullable string
erforderlich

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

prev_cursor
nullable string
erforderlich

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

refresh_cursor
nullable string
erforderlich

Refresh anchor, the first row of this response. Pass back as ending_before to fetch what precedes it in the current sort order. On a newest-first sort those are the items that have appeared since; on any other sort they are the items that sort earlier, so refreshing such a list means re-fetching it instead. Non-null whenever data is non-empty; null only on an empty page. Distinct from prev_cursor.

Verwandte Ressourcen

Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema.

Übung ausprobieren und ein Implementierungs-Briefing erhalten