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/searchAuthorizationToken Bearer · headerobligatorioA BillionSend API key (bs_…).
inbox_idstringobligatorioThe 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
objectstringobligatoriolisthas_morebooleanobligatoriodataobject[]obligatorioMostrar propiedadesOcultar propiedades
objectidstring<uuid>obligatoriosubjectstring | nullobligatoriofromstring | nullobligatoriotostring[]obligatorioccstring[]obligatoriobccstring[]obligatoriolabelsobject[]obligatorioMostrar propiedadesOcultar propiedades
objectidstring<uuid>obligatorionamestringobligatoriocolorstringobligatorioemail_countintegerobligatoriohas_attachmentbooleanobligatoriohas_draftbooleanobligatorioreadbooleanobligatorioquarantinedintegerBillionSend 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_atstringobligatoriofolderstringobligatorioinboxarchivespamsenttrashmatched_email_idstring<uuid> | nullobligatorioThe thread's best-matching email
highlightsobjectobligatorioFragments with match markers; only keys that matched; {} without query, or when only the text or an attachment name matched
Mostrar propiedadesOcultar propiedades
subjectstring[]fromstring[]tostring[]ccstring[]bccstring[]Missing, malformed, unknown or revoked API key
statusCodenumberobligatorionamestringobligatoriomessagestringobligatorioinclude_quarantined from an inbox-scoped key
statusCodenumberobligatorionamestringobligatoriomessagestringobligatorioInbox, label or cursor not found
statusCodenumberobligatorionamestringobligatoriomessagestringobligatorioValidation error
statusCodenumberobligatorionamestringobligatoriomessagestringobligatorioOver the rate limit (rate_limit_exceeded, with Retry-After)
statusCodenumberobligatorionamestringobligatoriomessagestringobligatoriosearch_unavailable: search is briefly unavailable; retry after the Retry-After seconds
statusCodenumberobligatorionamestringobligatoriomessagestringobligatorio