List messages
GET
/v1/email/messages
curl -X GET "https://us1.platform.bird.com/v1/email/messages" \
-H "Authorization: Bearer $TOKEN" \
--url-query "limit=25"Returns a paginated list of email messages in the workspace, newest first.
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.
created_after
string
Return only resources created strictly after this timestamp. RFC 3339 / ISO 8601 with timezone.
created_before
string
Return only resources created strictly before this timestamp. RFC 3339 / ISO 8601 with timezone.
status
string
Filter by aggregate delivery status.
tag
string
Filter by tag. Accepts name to match any send carrying that tag name, or name:value to match a specific tag pair (e.g. category:welcome). For filtering on arbitrary metadata fields, use the metadata path-filter parameters instead.
category
string
Filter by category.
to
string
Filter by recipient address. Exact match against any to/cc/bcc recipient on the message; normalised to lowercase before comparison.
from
string
Filter by sender address. Exact match against the message from field; normalised to lowercase before comparison.
Contenu de la réponse
data
array of object
obligatoire
Page of message objects.
Afficher les attributs enfants
data.id
string
obligatoire
Message ID.
data.from
object
obligatoire
Sender address. name is present when a display name was provided on the send.
Afficher les attributs enfants
data.from.email
string
obligatoire
Email address.
data.from.name
string
Display name shown alongside the address in mail clients.
data.to
array of object
obligatoire
Primary recipients. Length is the recipient count; use the broadcasts endpoint for audience-targeted sends. Each entry's name is present when a display name was provided on the send.
Afficher les attributs enfants
data.to.email
string
obligatoire
Email address.
data.to.name
string
Display name shown alongside the address in mail clients.
data.cc
array of object
CC recipients.
Afficher les attributs enfants
data.cc.email
string
obligatoire
Email address.
data.cc.name
string
Display name shown alongside the address in mail clients.
data.bcc
array of object
BCC recipients.
Afficher les attributs enfants
data.bcc.email
string
obligatoire
Email address.
data.bcc.name
string
Display name shown alongside the address in mail clients.
data.subject
string
obligatoire
Message subject line.
data.category
string
obligatoire
Content classification. Controls suppression policy — marketing blocks on all suppression reasons; transactional allows delivery through complaint and unsubscribe suppressions.
data.reply_to
nullable array
Reply-To addresses, if set on the send. Empty/null when no Reply-To was provided.
data.status
string
obligatoire
Aggregate delivery status derived from recipient states. scheduled means the message is queued to send at a future time and has not been dispatched yet. 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. canceled means a scheduled message was canceled before it was sent.
data.accepted_count
integer
obligatoire
Number of recipients currently in the accepted state — Bird has the send and is preparing to deliver.
data.processed_count
integer
obligatoire
Number of recipients for whom Bird has processed the message and queued it for delivery.
data.delivered_count
integer
obligatoire
Number of recipients whose messages were accepted by the remote MTA.
data.bounced_count
integer
obligatoire
Number of recipients that resulted in a permanent delivery failure.
data.complained_count
integer
obligatoire
Number of recipients that reported spam.
data.deferred_count
integer
obligatoire
Number of recipients in transient delivery deferral; the provider is retrying.
data.rejected_count
integer
obligatoire
Number of recipients rejected before delivery. See the per-recipient rejection_reason field on GET /v1/email/messages/{message_id}/recipients for the specific cause (suppression match, transmission failure, generation failure, or policy refusal).
data.processing_latency_ms
nullable integer
Time between Bird accepting the send and the message being processed for delivery, in milliseconds, for the fastest recipient. Null until the first recipient reaches processed.
data.delivery_latency_ms
nullable integer
Time between the message being processed and the receiving mail server accepting it, in milliseconds, for the fastest delivered recipient. Null until the first recipient is delivered.
data.total_latency_ms
nullable integer
End-to-end accept → delivered time for the fastest delivered recipient, in milliseconds. Null until the first recipient is delivered.
data.open_count
integer
obligatoire
Total open events across all recipients.
data.click_count
integer
obligatoire
Total click events across all recipients.
data.tags
array of object
Structured {name, value} filter labels applied to this send. See EmailMessageSendRequest for the tags vs metadata distinction.
Afficher les attributs enfants
data.tags.name
string
obligatoire
Tag name. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 32 characters.
data.tags.value
string
obligatoire
Tag value. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 64 characters.
data.metadata
object
Arbitrary JSON metadata stored on the message object and echoed in webhook payloads. See EmailMessageSendRequest for the tags vs metadata distinction.
data.attachments
array of object
Attachment metadata for the send. Empty when no attachments were included. Raw content is not echoed; use the future content-retrieval endpoint when storage is enabled.
Afficher les attributs enfants
data.attachments.id
string
Attachment ID, stable per email send.
data.attachments.filename
string
obligatoire
Filename as shown to the recipient.
data.attachments.content_type
string
Resolved MIME type at send time.
data.attachments.size
integer
obligatoire
Decoded size in bytes.
data.attachments.inline
boolean
True when the attachment was sent inline via a content_id reference in the HTML body, false for regular file attachments.
data.attachments.content_id
nullable string
The Content-ID set at send time, when the attachment was inline.
data.track_opens
boolean
obligatoire
Whether open tracking is enabled for this send.
data.track_clicks
boolean
obligatoire
Whether click tracking is enabled for this send.
data.created_at
string
obligatoire
When the send request was accepted.
data.thread_id
nullable string
Thread this message belongs to. Null until threading is enabled.
data.in_reply_to_message_id
nullable string
The message this one is a reply to, if any.
data.delivered_at
nullable string
When all recipients reached a terminal delivered state, or null if not yet fully delivered.
data.scheduled_at
nullable string
When this message is scheduled to send, for a send created with a future send time. Null for an immediate send. Stays set after the scheduled send fires.
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.