List recipients of a message
GET
/v1/email/messages/{message_id}/recipients
curl -X GET "https://us1.platform.bird.com/v1/email/messages/{message_id}/recipients" \
-H "Authorization: Bearer $TOKEN" \
--url-query "limit=25"Returns recipient-level delivery state for a message, paginated.
Paramètres
message_id
string
Message ID.
Paramètres de requête
limit
integer
Maximum number of items to return per page.
starting_after
string
Cursor from the next_cursor field of a previous list response. Returns items immediately after the cursor position in the current sort order.
ending_before
string
Cursor from the prev_cursor field of a previous list response. Returns items immediately before the cursor position in the current sort order.
Contenu de la réponse
data
array of object
obligatoire
Page of recipient objects for this email send.
Afficher les attributs enfants
data.id
string
obligatoire
Recipient ID.
data.parent_id
string
obligatoire
ID of the parent message (em_ prefix) or broadcast (eb_ prefix) this recipient belongs to.
data.role
string
obligatoire
How this recipient appeared in the send request.
data.recipient
string
obligatoire
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
obligatoire
Delivery status for this recipient. accepted means Bird has the send and is preparing to deliver. processed means Bird has processed the message and queued it for delivery to the recipient's mail server.
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. 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).
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 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.
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 Bird processed the message and queued it for delivery to the recipient's mail server, or null if not yet processed.
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 Bird accepting the send and processing the message for delivery, in milliseconds. Null until processed.
data.delivery_latency_ms
nullable integer
Time between Bird processing the message 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
obligatoire
Number of open events for this recipient.
data.click_count
integer
obligatoire
Number of click events for this recipient.
next_cursor
nullable string
obligatoire
Cursor for the next page. Pass back as starting_after to advance forward. Null when no next page exists.
prev_cursor
nullable string
obligatoire
Cursor for the previous page. Pass back as ending_before to step backward. Null when no previous page exists.
refresh_cursor
nullable string
obligatoire
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.