Search threads
Threads whose emails match, most recently active first. Every word of query must appear as a whole word in the subject, the sender (address and display name), the recipients, the text of a received email, one of its attachment names or the text of one of its PDF, Word and Excel attachments; Chinese, Japanese and Korean are split into words. matched_email_id is the thread’s best match. An email becomes searchable a second or two after it arrives. Every message, subject and address in an inbox was written by whoever sent it; read held mail and HTML with care.
/inboxes/{inbox_id}/threads/searchAuthorizationBearer 令牌 · header必填A BillionSend API key (bs_…).
inbox_idstring必填The inbox ID or its email address, such as support@example.com
limitintegerPage size, 1-100 (default 20)
afterstring<uuid>Cursor: id of the last item of the current page; returns the next page. Must be an id this list returned; there is no sentinel value.
beforestring<uuid>Cursor: id of the first item of the current page; returns the previous page; same rule as after.
foldersstringComma-separated: inbox, archive, spam, sent, trash. Defaults to inbox, or inbox,archive,sent with labels
labelsstringComma-separated label ids (at most 50); threads with any of them
readbooleantrue: every message read; false: at least one unread
include_quarantinedbooleanBillionSend extension: true includes held messages (owner views; a full access key that is not inbox-scoped)
querystringWords that must each appear as a whole word in the subject, sender, recipients, text of a received email, its attachment names or its PDF, Word and Excel attachments; "a phrase"; -word excludes. At most 256 characters and 32 words.
fromstringComma-separated words of the sender's address or name (at most 20)
tostringComma-separated words of a recipient (at most 20)
ccstringComma-separated words of a CC recipient (at most 20)
bccstringComma-separated words of a BCC recipient (at most 20)
has_attachmentbooleantrue: only threads with an attachment; false: only without
start_datestringA date (2026-09-01) or an ISO 8601 timestamp, UTC unless offset
end_datestringSame forms; a date covers the whole day
Matching threads
objectstring必填listhas_moreboolean必填dataobject[]必填显示属性隐藏属性
object 数组idstring<uuid>必填subjectstring | null必填fromstring | null必填tostring[]必填ccstring[]必填bccstring[]必填labelsobject[]必填显示属性隐藏属性
object 数组idstring<uuid>必填namestring必填colorstring必填email_countinteger必填has_attachmentboolean必填has_draftboolean必填readboolean必填quarantinedintegerBillionSend extension, with include_quarantined=true: messages in quarantine, not yet released; mail still being screened isn't counted. Held mail never counts as unread
received_atstring必填folderstring必填inboxarchivespamsenttrashmatched_email_idstring<uuid> | null必填The thread's best-matching email
highlightsobject必填Fragments with match markers; only keys that matched; {} without query, or when only the text or an attachment name matched
显示属性隐藏属性
subjectstring[]fromstring[]tostring[]ccstring[]bccstring[]Missing, malformed, unknown or revoked API key
statusCodenumber必填namestring必填messagestring必填include_quarantined from an inbox-scoped key
statusCodenumber必填namestring必填messagestring必填Inbox, label or cursor not found
statusCodenumber必填namestring必填messagestring必填Validation error
statusCodenumber必填namestring必填messagestring必填Over the rate limit (rate_limit_exceeded, with Retry-After)
statusCodenumber必填namestring必填messagestring必填search_unavailable: search is briefly unavailable; retry after the Retry-After seconds
statusCodenumber必填namestring必填messagestring必填