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/receivingAuthorizationToken Bearer · headerobrigatórioA 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
objectstringobrigatóriolisthas_morebooleanobrigatóriodataobject[]obrigatórioMostrar propriedadesOcultar propriedades
objectidstring<uuid>obrigatóriotostring[]obrigatóriofromstringobrigatórioBare address from the From header; the display name is in headers.from
created_atstringobrigatóriosubjectstringobrigatóriobccstring[]obrigatórioccstring[]obrigatórioreply_tostring[]obrigatórioreceived_forstring[]obrigatórioThe team's envelope recipients: the addresses the message was delivered to here
message_idstringobrigatórioattachmentsobject[]obrigatórioMostrar propriedadesOcultar propriedades
objectidstring<uuid>obrigatóriofilenamestring | nullobrigatóriocontent_typestringobrigatóriocontent_idstring | nullobrigatóriocontent_dispositionstring | nullobrigatóriosizeintegerobrigatórioinbox_idstring<uuid> | nullobrigatórioBillionSend 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> | nullobrigatórioBillionSend extension: that inbox's thread
inboxesobject[]BillionSend extension, full access keys only: every inbox the email reached and its screening verdict there
Mostrar propriedadesOcultar propriedades
objectinbox_idstring<uuid>obrigatóriothread_idstring<uuid>obrigatórioverdictstringobrigatóriopendingcleansuspiciousquarantinedreleasedspam_verdictstring | nullobrigatórioBillionSend extension: the local spam score's verdict; null for mail from before it existed
passgrayfailnullvirus_verdictstring | nullobrigatórioBillionSend 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
screeningobjectobrigatórioBillionSend extension: the screening verdict and the sender's trust tier
Mostrar propriedadesOcultar propriedades
verdictstringobrigatóriopendingcleansuspiciousquarantinedreleasedsender_truststringobrigatórioownerallowlistedknown_threadexternalunauthenticatedfailedextractedobjectobrigatórioBillionSend extension: whether a verification code or sign-in link was found; the values come with GET of one email
Mostrar propriedadesOcultar propriedades
kindsstring[]obrigatórioheldobject[]BillionSend extension, with wait only: matching mail that arrived but is held (being screened or quarantined), ids and why only
Mostrar propriedadesOcultar propriedades
objectidstring<uuid>obrigatórioinbox_idstring<uuid> | nullobrigatórioreasonstringobrigatóriopendingquarantinedquarantine_reasonstring | nullobrigatóriofailed_authunauthenticated_sendernot_allowlistedinjectionphishingvirusunscreenedscreening_capnullcreated_atstringobrigatórioMissing, malformed, unknown or revoked API key
statusCodenumberobrigatórionamestringobrigatóriomessagestringobrigatórioRestricted API key
statusCodenumberobrigatórionamestringobrigatóriomessagestringobrigatórioInbox not found
statusCodenumberobrigatórionamestringobrigatóriomessagestringobrigatórioValidation error
statusCodenumberobrigatórionamestringobrigatóriomessagestringobrigatórioToo many concurrent waits, or the rate limit (rate_limit_exceeded, with Retry-After)
statusCodenumberobrigatórionamestringobrigatóriomessagestringobrigatório