List events for a message
GET
/v1/email/messages/{message_id}/events
curl -X GET "https://us1.platform.bird.com/v1/email/messages/{message_id}/events" \
-H "Authorization: Bearer $TOKEN" \
--url-query "limit=25"Returns the message's per-recipient event timeline, oldest first, as a cursor page. Lifecycle, failure, and engagement events interleave as they happen, and engagement events (email.opened, email.clicked) can repeat per recipient. Filter to one event type with type. For each recipient's current state rather than its history, use List recipients of a message.
पैरामीटर
message_id
string
ID of the message whose timeline to read, from the send response's id field (em_-prefixed).
Query पैरामीटर
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, for example email.bounced or email.opened.
Possible values (may grow over time): email.accepted, email.bounced, email.canceled, email.clicked, email.complained, email.deferred, email.delivered, email.list_unsubscribed, email.opened, email.out_of_band_bounce, email.processed, email.rejected, email.scheduled, email.unsubscribed
Response Payload
data
array of object
आवश्यक
Page of timeline events for this email send, in chronological order.
चाइल्ड एट्रिब्यूट दिखाएँ
data.id
string
आवश्यक
Event ID.
data.type
string
आवश्यक
The event's type. email.processed, for example, means the message has been processed and queued for delivery.
Possible values (may grow over time): email.accepted, email.bounced, email.canceled, email.clicked, email.complained, email.deferred, email.delivered, email.list_unsubscribed, email.opened, email.out_of_band_bounce, email.processed, email.rejected, email.scheduled, email.unsubscribed
data.occurred_at
string
आवश्यक
When this event occurred.
data.recipient_id
string
आवश्यक
Recipient this event applies to.
data.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.
Possible values: hard, soft, undetermined, admin, block, null
data.bounce_class
nullable integer
A more detailed numeric bounce code, useful for telling apart failures that share the same bounce_type. For example, a DNS failure and a spam block can both come through as bounce_type: soft or bounce_type: block; this field tells you which one actually happened. Present on email.bounced, email.out_of_band_bounce, and email.deferred events.
data.bounce_code
nullable string
SMTP status code returned by the receiving mail server. Present on email.bounced and email.deferred events.
data.bounce_description
nullable string
The bounce reason, in plain language, as reported by the mail server. Present on email.bounced and email.deferred events.
data.rejection_reason
nullable string
Specific cause of rejection. Present on email.rejected events only.
- recipient_suppressed: The recipient is on the workspace suppression list.
- transmission_failed: The message could not be transmitted for delivery.
- generation_failure: The message could not be built for delivery, because of a 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: This recipient was not allowed for this send. For a send from the shared onboarding domain, every recipient has to be a verified member of the workspace.
Possible values: recipient_suppressed, transmission_failed, generation_failure, policy_rejection, domain_unverified, quota_exceeded, recipient_not_allowed, null
data.sending_ip
nullable string
The IP address used to send this message. Useful for spotting a deliverability problem that is tied to one specific sending IP rather than affecting all of them. Present on email.delivered, email.bounced, email.out_of_band_bounce, and email.deferred events.
data.is_prefetched
nullable boolean
True when the open was auto-fetched by an inbox privacy feature (Apple Mail Privacy Protection, the Gmail image proxy) rather than a person actually opening the message. Use it to calculate open rate accurately. Present on email.opened events only.
data.url
nullable string
The clicked URL. Present on email.clicked events.
data.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.
data.ip_address
nullable string
Client IP address (IPv4 or IPv6). Present on email.opened and email.clicked events when available.
data.user_agent
nullable string
Client user-agent string. Present on email.opened and email.clicked events when available.
next_cursor
nullable string
आवश्यक
Cursor for the next page. Pass back as starting_after to advance forward. Null when no next page exists.
prev_cursor
nullable string
आवश्यक
Cursor for the previous page. Pass back as ending_before to step backward. Null when no previous page exists.
refresh_cursor
nullable string
आवश्यक
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.