Documentation
Sign inGet started
Inizia ora
Guide
Riferimento API
SDK
CLI
Knowledge Base
Changelog

List messages

GET
/v1/email/messages
for await (const message of bird.email.list({ status: "bounced" })) {
  console.log(message.id);
}
Returns the workspace's sent and scheduled messages, newest first, as a cursor page. Each item has the aggregate delivery status and per-state recipient counts, not the message body.
Combine filters to narrow the page:
  • Delivery status.
  • Category.
  • Tag.
  • An exact to or from address.
  • A created_after or created_before time window.
Parametri di 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.
created_after
string
Return only resources created at or after this timestamp (inclusive lower bound). Combine with created_before to filter to a time window. RFC 3339 / ISO 8601 with timezone.
created_before
string
Return only resources created strictly before this timestamp (exclusive upper bound). Combine with created_after to filter to a time window. RFC 3339 / ISO 8601 with timezone.
status
string
Filter by aggregate delivery status.
Possible values: scheduled, accepted, processed, deferred, delivered, partial_failure, bounced, complained, rejected, canceled
tag
array
Filter by tag. Accepts name to match any message carrying that tag name, or name:value to match a specific tag pair (for example category:welcome). Repeat the parameter to add more tags. A message must match every tag listed to be returned.
category
string
Filter by category.
Possible values: marketing, transactional
to
string
Filter by recipient address. Exact match against any to/cc/bcc recipient on the message. The address is normalized to lowercase before comparison.
from
string
Filter by sender address. Exact match against the message from field. The address is normalized to lowercase before comparison.
Payload di risposta
data
array of object
obbligatorio
Page of message objects.
Mostra attributi secondari
data.id
string
obbligatorio
Message ID.
data.from
object
obbligatorio
Sender address. name is present when a display name was provided on the send.
Mostra attributi secondari
data.from.email
string
obbligatorio
Email address.
data.from.name
string
Display name shown alongside the address in mail clients.
data.to
array of object
obbligatorio
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.
Mostra attributi secondari
data.to.email
string
obbligatorio
Email address.
data.to.name
string
Display name shown alongside the address in mail clients.
data.cc
array of object
CC recipients.
Mostra attributi secondari
data.cc.email
string
obbligatorio
Email address.
data.cc.name
string
Display name shown alongside the address in mail clients.
data.bcc
array of object
BCC recipients.
Mostra attributi secondari
data.bcc.email
string
obbligatorio
Email address.
data.bcc.name
string
Display name shown alongside the address in mail clients.
data.subject
string
obbligatorio
The subject line as delivered. For a send that used a template, the stored subject is the template's, so this reports it with the send's parameters substituted in, which is what the recipient saw.
data.category
string
obbligatorio
Content classification, which controls suppression policy:
  • marketing: Blocks on all suppression reasons.
  • transactional: Allows delivery through complaint and unsubscribe suppressions, for receipts, password resets, and similar operational mail.
Possible values: marketing, transactional
data.reply_to
nullable array
Reply-To addresses, if set on the send. Empty/null when no Reply-To was provided.
data.status
string
obbligatorio
data.accepted_count
integer
obbligatorio
How many recipients are in the accepted state, meaning we have the message and are getting ready to deliver it.
data.processed_count
integer
obbligatorio
How many recipients the message has been prepared for and queued for delivery.
data.delivered_count
integer
obbligatorio
How many recipients' messages were accepted by their mail server.
data.bounced_count
integer
obbligatorio
Number of recipients that resulted in a permanent delivery failure.
data.complained_count
integer
obbligatorio
Number of recipients that reported spam.
data.deferred_count
integer
obbligatorio
Number of recipients in transient delivery deferral. Their mail server asked for a retry, and delivery attempts continue.
data.rejected_count
integer
obbligatorio
Number of recipients rejected before delivery. Read the per-recipient rejection_reason field on GET /v1/email/messages/{message_id}/recipients for the specific cause.
data.processing_latency_ms
nullable integer
Time between the send being accepted and the message being prepared 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
obbligatorio
Total open events across all recipients.
data.click_count
integer
obbligatorio
Total click events across all recipients.
data.requested_language
nullable string
The template language this send asked for, in canonical form (pt-BR for a request of pt-br). Null when the send named no language (it took the template's default) or used no template at all. Compare it with resolved_language: when they differ, the language you asked for was not available and the template's on_missing_language policy chose the one shown there instead.
data.resolved_language
nullable string
The template language this send was actually delivered in, in canonical form. Null when the send used no template. A non-null value with a null requested_language means the send named no language and took the template's default.
data.template_id
nullable string
The template this send rendered from, or null for a send that supplied its content inline.
data.template_version_id
nullable string
The exact template version this send rendered from, or null for an inline send. A template's live version changes every time you submit it, so this is what identifies the wording that was actually delivered, together with resolved_language.
data.tags
array of object
Labels on this message, each one a name and a value, that you can filter and search messages by. Use tags for anything you want to find messages by later, and metadata for data you only want handed back to you.
Mostra attributi secondari
data.tags.name
string
obbligatorio
Tag name. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 32 characters.
data.tags.value
string
obbligatorio
Tag value. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 64 characters.
data.metadata
object
Any JSON you kept on the message. We store it and hand it back in webhook payloads, and that is all it does. If you want to search or filter by it, use tags instead.
data.parameters
nullable object
The substitution values this send supplied, whether inline or from a template, or null if none were supplied. They are the values applied to subject and to the bodies the content endpoint returns, kept so you can see what produced the delivered copy and not only the result.
data.attachments
array of object
Attachment metadata for the send. Empty when no attachments were included. Raw content is not echoed. When content storage is enabled, download an attachment by its id via the message's attachment endpoint.
Mostra attributi secondari
data.attachments.id
string
Attachment ID, stable per email send.
data.attachments.filename
string
obbligatorio
Filename as shown to the recipient.
data.attachments.content_type
string
Resolved MIME type at send time.
data.attachments.size
integer
obbligatorio
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
obbligatorio
Whether open tracking is enabled for this send.
data.track_clicks
boolean
obbligatorio
Whether click tracking is enabled for this send.
data.created_at
string
obbligatorio
When the send request was accepted.
data.thread_id
nullable string
Thread this message belongs to, or null when the message is not part of one.
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
obbligatorio
Cursor for the next page. Pass back as starting_after to advance forward. Null when no next page exists.
prev_cursor
nullable string
obbligatorio
Cursor for the previous page. Pass back as ending_before to step backward. Null when no previous page exists.
refresh_cursor
nullable string
obbligatorio
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.