List a mailbox's messages
GET
/v1/email/mailboxes/{mailbox_id}/messages
curl -X GET "https://us1.platform.bird.com/v1/email/mailboxes/{mailbox_id}/messages" \
-H "Authorization: Bearer $TOKEN" \
--url-query "label=unread" \
--url-query "limit=25"Returns the messages in a mailbox across all of its conversations, newest first. By default only received messages in the inbox and all sent messages are returned; pass label to see another view instead — archive for filed-away mail, spam or blocked mail, trash for trashed messages, unread to answer "anything unread across all conversations?" in one call, or any custom label. Filter by direction or folded delivery status. Pass include=extracted_text to inline each message's extracted plain text. before and after filter by time; to page through results pass the response cursors back as starting_after or ending_before.
Query पैरामीटर
label
string
Filter to messages carrying this label. trash lists trashed messages; any other label — archive, spam, blocked, unread, or a custom label — lists its non-trashed carriers. When omitted, received messages in the inbox and all sent messages are returned.
direction
string
Filter to received (inbound) or sent (outbound) messages.
Possible values: inbound, outbound
status
string
Filter sent messages by folded delivery status: accepted, sent, delivered, or failed.
Possible values: accepted, sent, delivered, failed
after
string
Filter to messages that occurred at or after this time. This is a time filter, not a cursor.
before
string
Filter to messages that occurred at or before this time. This is a time filter, not a cursor.
include
string
Set to extracted_text to inline each message's extracted plain text.
Possible values: extracted_text
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.
Response Payload
data
array of object
आवश्यक
चाइल्ड एट्रिब्यूट दिखाएँ
data.id
string
आवश्यक
Message ID. Received messages carry a rem_ ID, sent messages an em_ ID — the same IDs used by the received-message and sent-message logs.
data.direction
string
आवश्यक
Direction of the message — inbound for a received message, outbound for a sent one.
Possible values: inbound, outbound
data.channel
string
आवश्यक
Channel this message was carried on. Always email.
data.thread_id
string
आवश्यक
Conversation this message belongs to.
data.from
string
आवश्यक
Sender address.
data.to
array of string
आवश्यक
Recipient addresses on the To line.
data.cc
array of string
आवश्यक
Recipient addresses on the Cc line. Empty when the message had none.
data.delivered_to
nullable string
आवश्यक
Address the message was actually delivered to, when it differs from the mailbox address (for example mail routed in from another address). Null for sent messages and for mail addressed directly to the mailbox.
data.subject
nullable string
आवश्यक
Message subject. Null when the message had no subject.
data.preview
nullable string
आवश्यक
Short plain-text preview of the message body.
data.extracted_text
nullable string
Plain-text content of the message with quoted history stripped — readable for the mailbox's full retention period, both directions. Always present when fetching a single message; on list endpoints it is included only when the request sets include=extracted_text. Null when no text could be extracted.
data.labels
array of string
आवश्यक
Labels on this message. System labels carry its state: a received message holds exactly one placement label — inbox for accepted mail, archive when its conversation was filed away, spam (failed sender authentication), or blocked (rejected by the mailbox's receive policy or rules) — plus unread until it is read. trash marks a message in the trash, either direction. Custom labels share the same list; a message carries at most 20.
data.status
nullable string
आवश्यक
Folded delivery status of a sent message: accepted, sent (provider handoff), delivered (all attempted recipients delivered), or failed (terminal failure). Null for received messages.
data.recipients
nullable array
आवश्यक
Terminal per-recipient delivery outcomes of a sent message, folded in as they become known — part of the message's durable memory. Null for received messages and before any recipient reaches a terminal state. Per-recipient event detail lives on the sent-message log (source) for 30 days.
data.authentication
nullable string
आवश्यक
Whether the sender of a 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 could be determined and the sender should not be treated as verified. Null for sent messages. Part of the message's durable memory — readable for the mailbox's full retention period, so the verdict survives after the 30-day inbound log has expired.
Possible values: pass, fail, unknown, null
data.spf_pass
nullable boolean
आवश्यक
Whether SPF passed for the sender of a received message. Null for sent messages and when no verdict is available. Durable for the mailbox's retention period.
data.dkim_pass
nullable boolean
आवश्यक
Whether DKIM passed for the sender of a received message. Null for sent messages and when no verdict is available. Durable for the mailbox's retention period.
data.dmarc_pass
nullable boolean
आवश्यक
Whether DMARC passed for the sender of a received message. Null for sent messages and when no verdict is available. Durable for the mailbox's retention period.
data.purge_at
string
आवश्यक
When the message will be permanently deleted: the end of the mailbox's retention period, pulled nearer (at most 30 days out) while the message is in the trash. Restore a trashed message before then with PATCH {"labels": {"remove": ["trash"]}}.
data.attachment_count
integer
आवश्यक
Number of attachments on the message.
data.attachment_manifest
array of object
आवश्यक
Attachment metadata (filename, content type, size). Remains readable for the mailbox's retention period even after the attachment bytes themselves have expired.
चाइल्ड एट्रिब्यूट दिखाएँ
data.attachment_manifest.id
string
आवश्यक
Attachment ID, used to download the attachment bytes.
data.attachment_manifest.filename
nullable string
आवश्यक
Original filename, or null when the attachment had none.
data.attachment_manifest.content_type
nullable string
आवश्यक
MIME content type, or null when it could not be determined.
data.attachment_manifest.size
integer
आवश्यक
Attachment size in bytes.
data.reference_ids
array of string
आवश्यक
RFC 5322 References header entries used to thread the conversation.
data.contact_id
nullable string
आवश्यक
Contact linked to this message, or null when none is linked.
data.source
object
आवश्यक
Link to the message's entry in the received-message or sent-message log, which carries delivery analytics such as per-recipient events. Log entries expire 30 days after the message occurred.
चाइल्ड एट्रिब्यूट दिखाएँ
data.source.resource
string
आवश्यक
API path of the log entry for this message.
data.source.available_until
string
आवश्यक
When the log entry (and the message's original rendered source) expires.
data.occurred_at
string
आवश्यक
When the message was received or accepted for sending.
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.