<Intro>

<EndpointHeader />

<Description>

Returns the workspace's sent and scheduled messages, newest first, as a cursor page. Each item carries the aggregate delivery `status` and per-state recipient counts, not the message body. Combine filters to narrow the page: `status`, `category`, `tag`, exact `to`/`from` address, and a `created_after`/`created_before` time window.

</Description>

</Intro>

<Parameters in="query">

<Parameter name="limit" type="integer">

<Description>

Maximum number of items to return per page.

</Description>

</Parameter>

<Parameter name="starting_after" type="string">

<Description>

Cursor from the `next_cursor` field of a previous list response. Returns items immediately after the cursor position in the current sort order.

</Description>

</Parameter>

<Parameter name="ending_before" type="string">

<Description>

Cursor from the `prev_cursor` field of a previous list response. Returns items immediately before the cursor position in the current sort order.

</Description>

</Parameter>

<Parameter name="created_after" type="string">

<Description>

Return only resources created strictly after this timestamp. RFC 3339 / ISO 8601 with timezone.

</Description>

</Parameter>

<Parameter name="created_before" type="string">

<Description>

Return only resources created strictly before this timestamp. RFC 3339 / ISO 8601 with timezone.

</Description>

</Parameter>

<Parameter name="status" type="string">

<Description>

Filter by aggregate delivery status.

</Description>

</Parameter>

<Parameter name="tag" type="array">

<Description>

Filter by tag. Accepts `name` to match any message carrying that tag name, or `name:value` to match a specific tag pair (e.g. `category:welcome`). Repeat the parameter to AND-combine several tag filters.

</Description>

</Parameter>

<Parameter name="category" type="string">

<Description>

Filter by category.

</Description>

</Parameter>

<Parameter name="to" type="string">

<Description>

Filter by recipient address. Exact match against any `to`/`cc`/`bcc` recipient on the message; normalised to lowercase before comparison.

</Description>

</Parameter>

<Parameter name="from" type="string">

<Description>

Filter by sender address. Exact match against the message `from` field; normalised to lowercase before comparison.

</Description>

</Parameter>

</Parameters>

<Payload kind="response">

<Field name="data" type="array of object" required>

<Description>

Page of message objects.

</Description>

<FieldChildren kind="response">

<Field name="id" type="string" prefix="data." required>

<Description>

Message ID.

</Description>

</Field>

<Field name="from" type="object" prefix="data." required>

<Description>

Sender address. `name` is present when a display name was provided on the send.

</Description>

<FieldChildren kind="response">

<Field name="email" type="string" prefix="data.from." required>

<Description>

Email address.

</Description>

</Field>

<Field name="name" type="string" prefix="data.from.">

<Description>

Display name shown alongside the address in mail clients.

</Description>

</Field>

</FieldChildren>

</Field>

<Field name="to" type="array of object" prefix="data." required>

<Description>

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.

</Description>

<FieldChildren kind="response">

<Field name="email" type="string" prefix="data.to." required>

<Description>

Email address.

</Description>

</Field>

<Field name="name" type="string" prefix="data.to.">

<Description>

Display name shown alongside the address in mail clients.

</Description>

</Field>

</FieldChildren>

</Field>

<Field name="cc" type="array of object" prefix="data.">

<Description>

CC recipients.

</Description>

<FieldChildren kind="response">

<Field name="email" type="string" prefix="data.cc." required>

<Description>

Email address.

</Description>

</Field>

<Field name="name" type="string" prefix="data.cc.">

<Description>

Display name shown alongside the address in mail clients.

</Description>

</Field>

</FieldChildren>

</Field>

<Field name="bcc" type="array of object" prefix="data.">

<Description>

BCC recipients.

</Description>

<FieldChildren kind="response">

<Field name="email" type="string" prefix="data.bcc." required>

<Description>

Email address.

</Description>

</Field>

<Field name="name" type="string" prefix="data.bcc.">

<Description>

Display name shown alongside the address in mail clients.

</Description>

</Field>

</FieldChildren>

</Field>

<Field name="subject" type="string" prefix="data." required>

<Description>

Message subject line.

</Description>

</Field>

<Field name="category" type="string" prefix="data." required>

<Description>

Content classification. Controls suppression policy — `marketing` blocks on all suppression reasons; `transactional` allows delivery through complaint and unsubscribe suppressions.

</Description>

<Description>

Possible values: `marketing`, `transactional`

</Description>

</Field>

<Field name="reply_to" type="nullable array" prefix="data.">

<Description>

Reply-To addresses, if set on the send. Empty/null when no Reply-To was provided.

</Description>

</Field>

<Field name="status" type="object" prefix="data." required>

<Description>

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.

</Description>

</Field>

<Field name="accepted_count" type="integer" prefix="data." required>

<Description>

Number of recipients currently in the `accepted` state — Bird has the send and is preparing to deliver.

</Description>

</Field>

<Field name="processed_count" type="integer" prefix="data." required>

<Description>

Number of recipients for whom Bird has processed the message and queued it for delivery.

</Description>

</Field>

<Field name="delivered_count" type="integer" prefix="data." required>

<Description>

Number of recipients whose messages were accepted by the remote MTA.

</Description>

</Field>

<Field name="bounced_count" type="integer" prefix="data." required>

<Description>

Number of recipients that resulted in a permanent delivery failure.

</Description>

</Field>

<Field name="complained_count" type="integer" prefix="data." required>

<Description>

Number of recipients that reported spam.

</Description>

</Field>

<Field name="deferred_count" type="integer" prefix="data." required>

<Description>

Number of recipients in transient delivery deferral; the provider is retrying.

</Description>

</Field>

<Field name="rejected_count" type="integer" prefix="data." required>

<Description>

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).

</Description>

</Field>

<Field name="processing_latency_ms" type="nullable integer" prefix="data.">

<Description>

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`.

</Description>

</Field>

<Field name="delivery_latency_ms" type="nullable integer" prefix="data.">

<Description>

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.

</Description>

</Field>

<Field name="total_latency_ms" type="nullable integer" prefix="data.">

<Description>

End-to-end accept → delivered time for the fastest delivered recipient, in milliseconds. Null until the first recipient is delivered.

</Description>

</Field>

<Field name="open_count" type="integer" prefix="data." required>

<Description>

Total open events across all recipients.

</Description>

</Field>

<Field name="click_count" type="integer" prefix="data." required>

<Description>

Total click events across all recipients.

</Description>

</Field>

<Field name="tags" type="array of object" prefix="data.">

<Description>

Structured `{name, value}` filter labels applied to this send. See EmailMessageSendRequest for the tags vs metadata distinction.

</Description>

<FieldChildren kind="response">

<Field name="name" type="string" prefix="data.tags." required>

<Description>

Tag name. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 32 characters.

</Description>

</Field>

<Field name="value" type="string" prefix="data.tags." required>

<Description>

Tag value. ASCII letters, digits, underscore, and hyphen only. Case-sensitive. Maximum 64 characters.

</Description>

</Field>

</FieldChildren>

</Field>

<Field name="metadata" type="object" prefix="data.">

<Description>

Arbitrary JSON metadata stored on the message object and echoed in webhook payloads. See EmailMessageSendRequest for the tags vs metadata distinction.

</Description>

</Field>

<Field name="attachments" type="array of object" prefix="data.">

<Description>

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.

</Description>

<FieldChildren kind="response">

<Field name="id" type="string" prefix="data.attachments.">

<Description>

Attachment ID, stable per email send.

</Description>

</Field>

<Field name="filename" type="string" prefix="data.attachments." required>

<Description>

Filename as shown to the recipient.

</Description>

</Field>

<Field name="content_type" type="string" prefix="data.attachments.">

<Description>

Resolved MIME type at send time.

</Description>

</Field>

<Field name="size" type="integer" prefix="data.attachments." required>

<Description>

Decoded size in bytes.

</Description>

</Field>

<Field name="inline" type="boolean" prefix="data.attachments.">

<Description>

True when the attachment was sent inline via a `content_id` reference in the HTML body, false for regular file attachments.

</Description>

</Field>

<Field name="content_id" type="nullable string" prefix="data.attachments.">

<Description>

The Content-ID set at send time, when the attachment was inline.

</Description>

</Field>

</FieldChildren>

</Field>

<Field name="track_opens" type="boolean" prefix="data." required>

<Description>

Whether open tracking is enabled for this send.

</Description>

</Field>

<Field name="track_clicks" type="boolean" prefix="data." required>

<Description>

Whether click tracking is enabled for this send.

</Description>

</Field>

<Field name="created_at" type="string" prefix="data." required>

<Description>

When the send request was accepted.

</Description>

</Field>

<Field name="thread_id" type="nullable string" prefix="data.">

<Description>

Thread this message belongs to. Null until threading is enabled.

</Description>

</Field>

<Field name="in_reply_to_message_id" type="nullable string" prefix="data.">

<Description>

The message this one is a reply to, if any.

</Description>

</Field>

<Field name="delivered_at" type="nullable string" prefix="data.">

<Description>

When all recipients reached a terminal delivered state, or null if not yet fully delivered.

</Description>

</Field>

<Field name="scheduled_at" type="nullable string" prefix="data.">

<Description>

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.

</Description>

</Field>

</FieldChildren>

</Field>

<Field name="next_cursor" type="nullable string" required>

<Description>

Cursor for the next page. Pass back as `starting_after` to advance forward. Null when no next page exists.

</Description>

</Field>

<Field name="prev_cursor" type="nullable string" required>

<Description>

Cursor for the previous page. Pass back as `ending_before` to step backward. Null when no previous page exists.

</Description>

</Field>

<Field name="refresh_cursor" type="nullable string" required>

<Description>

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`.

</Description>

</Field>

</Payload>