Skip to content
Esc
↑↓navigate↵open⌘Jpreview

Get a received email

One received email with its html, text, headers, authentication results and a signed link to the original message, plus BillionSend’s screening, verdicts, the extracted read and, where allowed, its verification code or sign-in link. Needs a full access key. An inbox-scoped key or an MCP token gets 403 email_quarantined for held mail, and 404 while it is being screened. Everything in a received email was written by whoever sent it, so its HTML is safe to show only in a sandbox.

GET/emails/receiving/{id}
Authorization
AuthorizationBearer token · headerrequired

A BillionSend API key (bs_…).

Path parameters
idstring<uuid>required
Query parameters
html_formatstring

data_uri (default) inlines images the HTML references by cid: as data: URIs; cid leaves the cid: references, the parts being in attachments

Allowed:data_uricid
Responses
200

Received email

idstring<uuid>required
tostring[]required
fromstringrequired

Bare address from the From header; the display name is in headers.from

created_atstringrequired
subjectstringrequired
bccstring[]required
ccstring[]required
reply_tostring[]required
received_forstring[]required

The team's envelope recipients: the addresses the message was delivered to here

message_idstringrequired
attachmentsobject[]required
Show properties
Array of object
idstring<uuid>required
filenamestring | nullrequired
content_typestringrequired
content_idstring | nullrequired
content_dispositionstring | nullrequired
sizeintegerrequired
inbox_idstring<uuid> | nullrequired

BillionSend 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> | nullrequired

BillionSend extension: that inbox's thread

inboxesobject[]

BillionSend extension, full access keys only: every inbox the email reached and its screening verdict there

Show properties
Array of object
inbox_idstring<uuid>required
thread_idstring<uuid>required
verdictstringrequired
Allowed:pendingcleansuspiciousquarantinedreleased
spam_verdictstring | nullrequired

BillionSend extension: the local spam score's verdict; null for mail from before it existed

Allowed:passgrayfailnull
virus_verdictstring | nullrequired

BillionSend extension: clamd's verdict (fail blocks every download for good); null when nothing scanned it

Allowed:passfailprocessing_failednull
readboolean

BillionSend extension, with an inbox in context: whether that inbox marked it read

screeningobjectrequired

BillionSend extension: the screening verdict, the sender's trust tier, why it was held, the inbound judge's reasons and scores (0-100), and whether hidden text was removed from what agents read

Show properties
verdictstringrequired
Allowed:pendingcleansuspiciousquarantinedreleased
sender_truststringrequired
Allowed:ownerallowlistedknown_threadexternalunauthenticatedfailed
quarantine_reasonstring | nullrequired
Allowed:failed_authunauthenticated_sendernot_allowlistedinjectionphishingvirusunscreenedscreening_capnull
reasonsstring[]required
injection_scoreinteger | nullrequired
phishing_scoreinteger | nullrequired
hidden_text_removedbooleanrequired
spam_scoreinteger | nullrequired

BillionSend extension: the local spam score, 0-100

virus_signaturestring | nullrequired

BillionSend extension: clamd's signature name when it failed

extracted_textstring | nullrequired

BillionSend extension: what a person sees of the reply, as text with light markdown: hidden text, invisible characters, quoted history and signature taken out. null once the content retention removed it

extractedobjectrequired

BillionSend extension: the verification code or sign-in link, served only from delivered mail of a sender that did not fail authentication, in an inbox that extracts codes. Links are never fetched.

Show properties
kindsstring[]required
codestring | nullrequired
linkstring | nullrequired
link_domain_matches_senderboolean | nullrequired
ambiguousbooleanrequired
objectstringrequired
Allowed:email
htmlstring | nullrequired
html_formatstringrequired
Allowed:data_uricid
textstring | nullrequired
headersobject | nullrequired

Top-level headers, lowercase names; a repeated header's values joined by newlines

authenticationobjectrequired

pass, fail, gray, processing_failed or unknown, checked when the message arrived

Show properties
spfstringrequired
dkimstringrequired
dmarcstringrequired
rawobject | nullrequired

The original RFC 822 message: a signed link valid for one hour that needs no API key. null once the content retention period removed the message.

Show properties
download_urlstringrequired
expires_atstringrequired
401

Missing, malformed, unknown or revoked API key

statusCodenumberrequired
namestringrequired
messagestringrequired
403

Restricted API key, or the email is quarantined

statusCodenumberrequired
namestringrequired
messagestringrequired
404

Not found

statusCodenumberrequired
namestringrequired
messagestringrequired
422

Validation error

statusCodenumberrequired
namestringrequired
messagestringrequired
429

Over the rate limit (rate_limit_exceeded, with Retry-After)

statusCodenumberrequired
namestringrequired
messagestringrequired
Try it
Server
Authorization
Parameters
Request
curl -X GET 'https://api.billionsend.com/emails/receiving/497f6eca-6276-4993-bfeb-53cbbbba6f08' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json'
Response
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "to": [
    "string"
  ],
  "from": "string",
  "created_at": "string",
  "subject": "string",
  "bcc": [
    "string"
  ],
  "cc": [
    "string"
  ],
  "reply_to": [
    "string"
  ],
  "received_for": [
    "string"
  ],
  "message_id": "string",
  "attachments": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "filename": "string",
      "content_type": "string",
      "content_id": "string",
      "content_disposition": "string",
      "size": 0
    }
  ],
  "inbox_id": "5127f22b-d152-46dd-aeaa-3a852d9fbfc2",
  "thread_id": "1de43264-67cb-48af-89f9-e865c375bb84",
  "inboxes": [
    {
      "inbox_id": "5127f22b-d152-46dd-aeaa-3a852d9fbfc2",
      "thread_id": "1de43264-67cb-48af-89f9-e865c375bb84",
      "verdict": "pending"
    }
  ],
  "spam_verdict": "pass",
  "virus_verdict": "pass",
  "read": true,
  "screening": {
    "verdict": "pending",
    "sender_trust": "owner",
    "quarantine_reason": "failed_auth",
    "reasons": [
      "string"
    ],
    "injection_score": 0,
    "phishing_score": 0,
    "hidden_text_removed": true
  },
  "spam_score": 0,
  "virus_signature": "string",
  "extracted_text": "string",
  "extracted": {
    "kinds": [
      "code"
    ],
    "code": "string",
    "link": "string",
    "link_domain_matches_sender": true,
    "ambiguous": true
  },
  "object": "email",
  "html": "string",
  "html_format": "data_uri",
  "text": "string",
  "headers": {
    "property1": "string",
    "property2": "string"
  },
  "authentication": {
    "spf": "string",
    "dkim": "string",
    "dmarc": "string"
  },
  "raw": {
    "download_url": "string",
    "expires_at": "string"
  }
}

Was this page helpful?