<Intro>

<EndpointHeader />

<Description>

Returns a paginated list of received emails for the workspace, newest first. Filter by sender address, by the inbound address that received the mail, or by a received-time range. Received emails are retained for 30 days.

</Description>

</Intro>

<Parameters in="query">

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

<Description>

Filter to messages whose sender address matches this value.

</Description>

</Parameter>

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

<Description>

Filter to messages received on a specific Bird-minted inbound address.

</Description>

</Parameter>

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

<Description>

Filter to messages received at or after this time.

</Description>

</Parameter>

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

<Description>

Filter to messages received at or before this time.

</Description>

</Parameter>

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

</Parameters>

<Payload kind="response">

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

<Description>

Page of received emails, newest first.

</Description>

<FieldChildren kind="response">

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

<Description>

Received message ID.

</Description>

</Field>

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

<Description>

Sender address parsed from the message.

</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>

Recipients on the message's To header.

</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." required>

<Description>

Recipients on the message's Cc header.

</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="subject" type="nullable string" prefix="data." required>

<Description>

Subject line as received, or null when the message had no subject.

</Description>

</Field>

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

<Description>

RFC 5322 Message-ID header from the sender, or null when the sender did not include one.

</Description>

</Field>

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

<Description>

In-Reply-To header — the Message-ID this message replies to, or null when it is not a reply.

</Description>

</Field>

<Field name="references" type="array of string" prefix="data.">

<Description>

References header — the chain of Message-IDs in this conversation, oldest first. Absent when the message had no References header.

</Description>

</Field>

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

<Description>

Conversation this message belongs to. Always null until threading is available.

</Description>

</Field>

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

<Description>

Whether the sender of the received message was authenticated. `pass` means the sender's identity was verified; `fail` means it was checked and did not verify; `unknown` means no verdict is available and the sender should not be treated as verified.

</Description>

<Description>

Possible values: `pass`, `fail`, `unknown`, `null`

</Description>

</Field>

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

<Description>

Whether SPF passed for the sender, parsed from the message's authentication results. Null when the result did not carry an SPF verdict.

</Description>

</Field>

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

<Description>

Whether DKIM passed for the sender, parsed from the message's authentication results. Null when the result did not carry a DKIM verdict.

</Description>

</Field>

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

<Description>

Whether DMARC passed for the sender, parsed from the message's authentication results. Null when the result did not carry a DMARC verdict.

</Description>

</Field>

<Field name="spam_score" type="nullable number" prefix="data." required>

<Description>

Spam score for the message. Always null at present; reserved for a future content-scoring capability.

</Description>

</Field>

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

<Description>

Metadata for each attachment found on the message. Empty when the message had no attachments.

</Description>

<FieldChildren kind="response">

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

<Description>

Attachment ID, stable within the received message.

</Description>

</Field>

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

<Description>

Filename from the attachment's Content-Disposition, or null when the sender did not name the part.

</Description>

</Field>

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

<Description>

MIME type parsed from the attachment part, or null when absent.

</Description>

</Field>

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

<Description>

Size of the attachment in bytes.

</Description>

</Field>

</FieldChildren>

</Field>

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

<Description>

When Bird received the message.

</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>