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/receivingAuthorizationBearer token · headerrequiredA 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
objectstringrequiredlisthas_morebooleanrequireddataobject[]requiredShow propertiesHide properties
objectidstring<uuid>requiredtostring[]requiredfromstringrequiredBare address from the From header; the display name is in headers.from
created_atstringrequiredsubjectstringrequiredbccstring[]requiredccstring[]requiredreply_tostring[]requiredreceived_forstring[]requiredThe team's envelope recipients: the addresses the message was delivered to here
message_idstringrequiredattachmentsobject[]requiredShow propertiesHide properties
objectidstring<uuid>requiredfilenamestring | nullrequiredcontent_typestringrequiredcontent_idstring | nullrequiredcontent_dispositionstring | nullrequiredsizeintegerrequiredinbox_idstring<uuid> | nullrequiredBillionSend 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> | nullrequiredBillionSend extension: that inbox's thread
inboxesobject[]BillionSend extension, full access keys only: every inbox the email reached and its screening verdict there
Show propertiesHide properties
objectinbox_idstring<uuid>requiredthread_idstring<uuid>requiredverdictstringrequiredpendingcleansuspiciousquarantinedreleasedspam_verdictstring | nullrequiredBillionSend extension: the local spam score's verdict; null for mail from before it existed
passgrayfailnullvirus_verdictstring | nullrequiredBillionSend 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
screeningobjectrequiredBillionSend extension: the screening verdict and the sender's trust tier
Show propertiesHide properties
verdictstringrequiredpendingcleansuspiciousquarantinedreleasedsender_truststringrequiredownerallowlistedknown_threadexternalunauthenticatedfailedextractedobjectrequiredBillionSend extension: whether a verification code or sign-in link was found; the values come with GET of one email
Show propertiesHide properties
kindsstring[]requiredheldobject[]BillionSend extension, with wait only: matching mail that arrived but is held (being screened or quarantined), ids and why only
Show propertiesHide properties
objectidstring<uuid>requiredinbox_idstring<uuid> | nullrequiredreasonstringrequiredpendingquarantinedquarantine_reasonstring | nullrequiredfailed_authunauthenticated_sendernot_allowlistedinjectionphishingvirusunscreenedscreening_capnullcreated_atstringrequiredMissing, malformed, unknown or revoked API key
statusCodenumberrequirednamestringrequiredmessagestringrequiredRestricted API key
statusCodenumberrequirednamestringrequiredmessagestringrequiredInbox not found
statusCodenumberrequirednamestringrequiredmessagestringrequiredValidation error
statusCodenumberrequirednamestringrequiredmessagestringrequiredToo many concurrent waits, or the rate limit (rate_limit_exceeded, with Retry-After)
statusCodenumberrequirednamestringrequiredmessagestringrequired