List events for a message
GET
/v1/email/messages/{message_id}/events
Returns the per-recipient event timeline 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.
type
string
Filter by event type (e.g. email.bounced, email.opened).
Response Payload
data
array of object
required
Page of timeline events for this email send, in chronological order.
Show child attributes
id
string
required
Event ID.
type
string
required
Event type. One of: email.accepted, email.processed, email.deferred, email.delivered, email.bounced, email.out_of_band_bounce, email.complained, email.rejected, email.opened, email.clicked, email.unsubscribed, email.list_unsubscribed.
email.processed means Bird has processed the message and queued it for delivery.
occurred_at
string
required
When this event occurred.
recipient_id
string
required
Recipient this event applies to.
bounce_type
nullable string
Bounce classification. Present on email.bounced, email.out_of_band_bounce, and email.deferred events. 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.
bounce_class
nullable integer
Numeric bounce classification for fine-grained deliverability triage. Lets you distinguish, for example, a DNS failure from a spam block when both would be bounce_type: soft or bounce_type: block. Present on email.bounced, email.out_of_band_bounce, and email.deferred.
bounce_code
nullable string
SMTP status code returned by the receiving mail server. Present on email.bounced and email.deferred events.
bounce_description
nullable string
Human-readable bounce reason. Present on email.bounced and email.deferred events.
rejection_reason
nullable string
Specific cause of rejection. Present on email.rejected events only. See EmailRecipient.rejection_reason for the meaning of each value.
sending_ip
nullable string
The IP address Bird used to send this message. Useful when investigating deliverability issues that correlate with specific IPs. Present on email.delivered, email.bounced, email.out_of_band_bounce, and email.deferred events.
is_prefetched
nullable boolean
True when the open was auto-fetched by an inbox privacy feature (Apple Mail Privacy Protection, Gmail image proxy) rather than a real user action. Useful for accurate open-rate calculation. Present on email.opened only.
url
nullable string
The clicked URL. Present on email.clicked events.
country
nullable string
ISO 3166-1 alpha-2 country code derived from the client IP. Present on email.opened and email.clicked events when available.
ip_address
nullable string
Client IP address (IPv4 or IPv6). Present on email.opened and email.clicked events when available.
user_agent
nullable string
Client user-agent string. Present on email.opened and email.clicked events when available.
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}/events" \
-H "Authorization: Bearer $TOKEN" \
--url-query "limit=25"