List threads
GET
/v1/email/threads
curl -X GET "https://us1.platform.bird.com/v1/email/threads" \
-H "Authorization: Bearer $TOKEN" \
--url-query "label=urgent" \
--url-query "participant=billing@acme.com" \
--url-query "subject=quarterly invoice" \
--url-query "limit=25"Returns a paginated list of conversations across the workspace's mailboxes, most recently active first. label selects the view: the inbox (the default when omitted), archive, spam, blocked, or any custom label. Filter by mailbox, linked contact, or last-activity time, or pass q to full-text search conversations by their messages' subject and text. Conversations whose every message has been trashed are omitted; restoring a message returns its conversation to the list. before and after filter by time; to page through results pass the response cursors back as starting_after or ending_before.
Parâmetros de consulta
mailbox_id
string
Filter to conversations in a specific mailbox.
contact_id
string
Filter to conversations linked to a specific contact.
label
array
Filter to conversations carrying this label. Repeat the parameter to require several — only conversations carrying every listed label match. A placement label selects a folder (inbox, archive, spam, blocked); a custom label matches conversations in any folder. Defaults to inbox when omitted.
has_unread
boolean
When true, only conversations with unread messages are returned. This filters on the conversation's unread state, so it combines with label — for example, unread conversations in the archive. (The unread label itself lives on messages, not conversations.)
participant
string
Conversations involving this address — matches the sender or any recipient, as a case-insensitive contains-match, so a full address or any fragment of one works.
subject
string
Conversations whose subject contains this text (case-insensitive).
after
string
Filter to conversations whose most recent message is at or after this time. This is a time filter, not a cursor.
before
string
Filter to conversations whose most recent message is at or before this time. This is a time filter, not a cursor.
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.
Payload de resposta
data
array of object
obrigatório
Mostrar atributos secundários
data.id
string
obrigatório
Thread ID.
data.mailbox_id
string
obrigatório
Mailbox this conversation belongs to.
data.channel
string
obrigatório
Channel this conversation lives on. Always email.
data.contact_id
nullable string
obrigatório
Contact linked to this conversation, or null when none is linked.
data.subject
nullable string
obrigatório
Subject of the conversation, taken from its first message. Null when that message had no subject.
data.participants
array of string
obrigatório
Addresses that appear on the retained messages in this conversation, including the mailbox's own address.
data.message_count
integer
obrigatório
Number of retained messages in this conversation, both directions.
data.unread_count
integer
obrigatório
Number of retained received messages that are still unread. Spam and blocked mail is not counted.
data.last_message_at
string
obrigatório
When the most recent retained message in this conversation was received or sent.
data.last_direction
string
obrigatório
Direction of the most recent message — inbound for a received message, outbound for a sent one.
Possible values: inbound, outbound
data.labels
array of string
obrigatório
Labels on this conversation. Exactly one system placement label is always present — inbox, archive (filed away, done for now), spam (the opening message failed sender authentication), or blocked (rejected by the mailbox's receive policy or rules) — set by the message that started the conversation. Move a conversation by updating its labels: add spam to file it as spam, add archive to clean it out of the inbox, and add inbox — or remove spam, blocked, or archive — to bring it back. An archived conversation returns to the inbox by itself when a new message arrives. Custom labels share the same list; a conversation carries at most 20.
data.created_at
string
obrigatório
When the thread was created.
data.updated_at
string
obrigatório
When the thread last changed.
data.highlights
object
Matched search fragments, keyed by the field that matched. Returned only by thread search; omitted when listing threads.
Mostrar atributos secundários
data.highlights.subject
array of string
Matched fragments from the conversation's subject.
data.highlights.text
array of string
Matched fragments from a message's body text.
next_cursor
nullable string
obrigatório
Cursor for the next page. Pass back as starting_after to advance forward. Null when no next page exists.
prev_cursor
nullable string
obrigatório
Cursor for the previous page. Pass back as ending_before to step backward. Null when no previous page exists.
refresh_cursor
nullable string
obrigatório
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.