List recipients of a message
GET
/v1/email/messages/{message_id}/recipients
Returns recipient-level delivery state for a message, paginated.
Parameters
message_id
string
Message ID.
Query Parameters
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.
Response Payload
data
array of object
required
Page of recipient objects for this email send.
Show child attributes
id
string
required
Recipient ID.
parent_id
string
required
ID of the parent message (em_ prefix) or broadcast (eb_ prefix) this recipient belongs to.
role
string
required
How this recipient appeared in the send request.
recipient
string
required
Recipient email address.
name
nullable string
Display name provided for this recipient on the send, or null if none was given.
status
string
required
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.
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.
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.
delivered_at
nullable string
When the recipient's mail server accepted the message, or null if not yet delivered.
processing_latency_ms
nullable integer
Time between Bird accepting the send and processing the message for delivery, in milliseconds. Null until processed.
delivery_latency_ms
nullable integer
Time between Bird processing the message and the receiving mail server accepting it, in milliseconds. Null until delivered.
total_latency_ms
nullable integer
End-to-end accept → delivered time for this recipient, in milliseconds. Null until delivered.
open_count
integer
required
Number of open events for this recipient.
click_count
integer
required
Number of click events for this recipient.
next_cursor
nullable string
required
Cursor for the next page. Pass back as starting_after to advance forward. Null when no next page exists.
prev_cursor
nullable string
required
Cursor for the previous page. Pass back as ending_before to step backward. Null when no previous page exists.
refresh_cursor
nullable string
required
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.
cURL
curl -X GET "https://us1.platform.bird.com/v1/email/messages/{message_id}/recipients" \
-H "Authorization: Bearer $TOKEN" \
--url-query "limit=25"