List received emails
Mail received at the team’s receiving domains and inboxes, newest first (after pages toward older mail), with cursor pagination. Needs a full access key; a domain-scoped key lists mail addressed to its domain only, an inbox-scoped key mail delivered into its inbox. Mail held for screening or in quarantine is left out unless a full access key asks for it (include_quarantined, quarantined). With wait, the request is held until matching mail arrives (long-poll). An inbox_id the key can’t reach answers 404 at once, without waiting; an inbox-scoped key naming another inbox gets 403 restricted_api_key. Everything in a received email was written by whoever sent it, so its HTML is safe to show only in a sandbox.
/emails/receivingAuthorizationJeton Bearer · headerrequisA BillionSend API key (bs_…).
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.
waitintegerBillionSend extension: hold the request up to this many seconds (0-50) until matching mail newer than the cursor arrives; an empty list with 200 when none did
sincestring<date-time>BillionSend extension: only mail received after this instant; with wait and no cursor it defaults to one minute before the request
inbox_idstring<uuid>BillionSend extension: only mail delivered into this inbox
tostringBillionSend extension: only mail with this address in received_for
fromstringBillionSend extension: a sender address, or a domain matching itself and its subdomains
subject_containsstringBillionSend extension: case-insensitive subject substring
unreadstringBillionSend extension, with an inbox in context (inbox_id, or an inbox-scoped key): read state in that inbox
truefalseinclude_quarantinedstringBillionSend extension, full access keys only: list held mail too, flagged by screening
truefalsequarantinedstringBillionSend extension, full access keys only: list held mail only
truefalseReceived emails
objectstringrequislisthas_morebooleanrequisdataobject[]requisAfficher les propriétésMasquer les propriétés
objectidstring<uuid>requistostring[]requisfromstringrequisBare address from the From header; the display name is in headers.from
created_atstringrequissubjectstringrequisbccstring[]requisccstring[]requisreply_tostring[]requisreceived_forstring[]requisThe team's envelope recipients: the addresses the message was delivered to here
message_idstringrequisattachmentsobject[]requisAfficher les propriétésMasquer les propriétés
objectidstring<uuid>requisfilenamestring | nullrequiscontent_typestringrequiscontent_idstring | nullrequiscontent_dispositionstring | nullrequissizeintegerrequisinbox_idstring<uuid> | nullrequisBillionSend extension: the inbox this read is about (an inbox-scoped key's own, the inbox_id filter's, else the oldest inbox the email reached); null for mail no inbox took
thread_idstring<uuid> | nullrequisBillionSend extension: that inbox's thread
inboxesobject[]BillionSend extension, full access keys only: every inbox the email reached and its screening verdict there
Afficher les propriétésMasquer les propriétés
objectinbox_idstring<uuid>requisthread_idstring<uuid>requisverdictstringrequispendingcleansuspiciousquarantinedreleasedspam_verdictstring | nullrequisBillionSend extension: the local spam score's verdict; null for mail from before it existed
passgrayfailnullvirus_verdictstring | nullrequisBillionSend extension: clamd's verdict (fail blocks every download for good); null when nothing scanned it
passfailprocessing_failednullreadbooleanBillionSend extension, with an inbox in context: whether that inbox marked it read
screeningobjectrequisBillionSend extension: the screening verdict and the sender's trust tier
Afficher les propriétésMasquer les propriétés
verdictstringrequispendingcleansuspiciousquarantinedreleasedsender_truststringrequisownerallowlistedknown_threadexternalunauthenticatedfailedextractedobjectrequisBillionSend extension: whether a verification code or sign-in link was found; the values come with GET of one email
Afficher les propriétésMasquer les propriétés
kindsstring[]requisheldobject[]BillionSend extension, with wait only: matching mail that arrived but is held (being screened or quarantined), ids and why only
Afficher les propriétésMasquer les propriétés
objectidstring<uuid>requisinbox_idstring<uuid> | nullrequisreasonstringrequispendingquarantinedquarantine_reasonstring | nullrequisfailed_authunauthenticated_sendernot_allowlistedinjectionphishingvirusunscreenedscreening_capnullcreated_atstringrequisMissing, malformed, unknown or revoked API key
statusCodenumberrequisnamestringrequismessagestringrequisRestricted API key
statusCodenumberrequisnamestringrequismessagestringrequisInbox not found
statusCodenumberrequisnamestringrequismessagestringrequisValidation error
statusCodenumberrequisnamestringrequismessagestringrequisToo many concurrent waits, or the rate limit (rate_limit_exceeded, with Retry-After)
statusCodenumberrequisnamestringrequismessagestringrequis