Search a mailbox's messages
GET
/v1/email/mailboxes/{mailbox_id}/messages/search
curl -X GET "https://us1.platform.bird.com/v1/email/mailboxes/{mailbox_id}/messages/search" \
-H "Authorization: Bearer $TOKEN" \
--url-query "q=refund invoice" \
--url-query "limit=25"Full-text search over the mailbox's durable memory, both directions — subjects and extracted text of received and sent messages — so "what did I already tell this customer?" is one call. Results are flat messages ranked by relevance and carry thread_id for client-side conversation grouping, plus a rank score. Only messages in the default view are searched: received messages in the inbox and all sent messages, excluding trashed mail. The search index lives as long as the mailbox's retention tier. Results are ordered by descending relevance rank, then occurred_at and message id descending as a stable tiebreak; page through them by passing the response next_cursor back as starting_after (or prev_cursor as ending_before). At most 100 results are returned per page.
Queryparameters
q
string
Search query. Plain words match all terms; quoted phrases and - exclusions are supported.
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
verplicht
Onderliggende attributen tonen
data.id
string
verplicht
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
verplicht
Direction of the message — inbound for a received message, outbound for a sent one.
data.channel
string
verplicht
Channel this message was carried on. Always email.
data.thread_id
string
verplicht
Conversation this message belongs to.
data.from
string
verplicht
Sender address.
data.to
array of string
verplicht
Recipient addresses on the To line.
data.cc
array of string
verplicht
Recipient addresses on the Cc line. Empty when the message had none.
data.delivered_to
nullable string
verplicht
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
verplicht
Message subject. Null when the message had no subject.
data.preview
nullable string
verplicht
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.read
nullable boolean
verplicht
Whether the message has been marked read. Null for sent messages.
data.disposition
nullable string
verplicht
Where the message landed: inbox for accepted mail, blocked (receive policy or rules), or unauthenticated (failed sender authentication). Null for sent messages. Trash state is carried separately in trashed_at.
data.status
nullable string
verplicht
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
verplicht
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.spf_pass
nullable boolean
verplicht
Whether SPF passed for the sender of a received message. Null for sent messages and when no verdict was computable. 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.
data.dkim_pass
nullable boolean
verplicht
Whether DKIM passed for the sender of a received message. Null for sent messages and when no verdict was computable. Durable for the mailbox's retention period.
data.dmarc_pass
nullable boolean
verplicht
Whether DMARC passed for the sender of a received message. Null for sent messages and when no verdict was computable. Durable for the mailbox's retention period.
data.trashed_at
nullable string
verplicht
When the message was moved to the trash, or null when it is not trashed. Trashed messages are purged 30 days after trashing; restore it with PATCH {"trashed": false} before then.
data.rank
number
Relevance rank of this result. Present only on search results, higher is more relevant.
data.attachment_count
integer
verplicht
Number of attachments on the message.
data.attachment_manifest
array of object
verplicht
Attachment metadata (filename, content type, size). Remains readable for the mailbox's retention period even after the attachment bytes themselves have expired.
Onderliggende attributen tonen
data.attachment_manifest.id
string
verplicht
Attachment ID, used to download the attachment bytes.
data.attachment_manifest.filename
nullable string
verplicht
Original filename, or null when the attachment had none.
data.attachment_manifest.content_type
nullable string
verplicht
MIME content type, or null when it could not be determined.
data.attachment_manifest.size
integer
verplicht
Attachment size in bytes.
data.reference_ids
array of string
verplicht
RFC 5322 References header entries used to thread the conversation.
data.labels
array of string
verplicht
Labels applied to this message. A message carries at most 20 labels.
data.contact_id
nullable string
verplicht
Contact linked to this message, or null when none is linked.
data.source
object
verplicht
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.
Onderliggende attributen tonen
data.source.resource
string
verplicht
API path of the log entry for this message.
data.source.available_until
string
verplicht
When the log entry (and the message's original rendered source) expires.
data.occurred_at
string
verplicht
When the message was received or accepted for sending.
next_cursor
nullable string
verplicht
Cursor for the next page. Pass back as starting_after to advance forward. Null when no next page exists.
prev_cursor
nullable string
verplicht
Cursor for the previous page. Pass back as ending_before to step backward. Null when no previous page exists.
refresh_cursor
nullable string
verplicht
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.