Skip to content
Esc
↑↓navigate↵open⌘Jpreview
On this page

Receiving

Receive email on your own domain and read it through the API, webhooks and the dashboard.

Receiving turns a domain you verified into a place that takes mail. Incoming messages are stored encrypted and reach you through the API, the email.received webhook, the dashboard (Inboxes → All received) and the MCP server.

Two ways to choose which addresses take mail: create an inbox for an address, or turn on catch-all to take every other address of the domain.

Set up

  1. Pick a name that receives no mail yet, such as inbound.example.com. The MX record takes over every address on the name it is published on, so your mailboxes at example.com stay with your current provider.

  2. Add and verify that exact name under Domains, as for sending. Verifying example.com does not cover its subdomains.

  3. Turn on receiving: open the domain and switch on Enable receiving, or call the API:

    curl -X PATCH "https://api.billionsend.com/domains/{id}" \
      -H "Authorization: Bearer bs_..." \
      -H "Content-Type: application/json" \
      -d '{ "capabilities": { "receiving": "enabled" } }'

    A name can receive in one team only; a name another team already receives on answers 409.

  4. Publish both MX records shown in the domain’s records, at your DNS provider:

    Type Name Value Priority
    MX inbound.example.com mx1.billionsend-dns.com 10
    MX inbound.example.com mx2.billionsend-dns.com 10

    Each is a separate mail server. With both published, a sender that finds one of them down retries on the other within seconds, so publish both at the same priority. Each row turns verified once no other MX record on that name has a lower priority number.

  5. Choose the addresses: create an inbox for each address, or switch on Catch-all on the domain page. With neither, the domain refuses all mail.

  6. Send a test from any mailbox. It shows under Inboxes → All received within seconds.

To stop receiving, switch it off ("receiving": "disabled") and remove the MX record. Mail already stored stays until retention removes it.

Which addresses receive

  • The address of each inbox on the domain, and its +tag variants: orders+4821@ reaches the inbox of orders@.
  • With catch-all on, every other address too: support@, invoices@, reply+ticket-4821@. Read received_for in your code to see which address a message came to.

With catch-all off, any other address is refused while the sender’s server is still connected (550 5.1.1), so the sender gets a bounce from their own server and nothing is stored.

Catch-all is off by default and needs a paid plan (Free answers 403 plan_limit_reached). Owners, admins and developers switch it on the domain page, or with PATCH /domains/{id} and { "receiving_catch_all": true }.

  • received_for lists the addresses at your domains the message was actually delivered to, Bcc included. to and cc are only what the headers claim, so route on received_for.
  • A message is stored once per team, however many of your addresses it was sent to.
  • Only the exact name receives: mail to x@eu.inbound.example.com is refused unless that subdomain receives too.

Filtering and limits

Settings → Receiving has three switches. They apply to every domain of your team and take effect on the next message.

Switch On Off
Reject spam above score 5 (default on) Mail with a spam score of 5 or more (on a 0 to 10 scale) is refused with 554 5.7.1; nothing is stored. Spam is stored: in the spam folder of an inbox, only flagged at a catch-all address.
Strip attachments over 10 MB (default off) Each larger attachment is replaced by a short <file>.removed.txt note saying what was removed. Attachments are stored as they came.
Keep raw .eml for 30 days (default on) Content stays for your retention window. Content (text, HTML, headers, raw message, attachments) is deleted after 1 day. Metadata and webhooks are unaffected.
Limit Free Starter, Pro, Scale
Message size 10 MB 40 MB
Catch-all No Yes
Received mail 100 per UTC day 2 times your plan’s monthly volume, each month
Past that Deferred until midnight UTC Deferred until your volume renews
Retention 30 days 30 days
  • Size counts the whole stored message after attachment stripping. Base64 makes attachments about a third larger, so on 40 MB roughly 30 MB of files fit. A larger message is refused with 552 5.3.4.
  • Received mail counts once per message per team, against its own limit. It never uses your sending volume, and sending never uses your receiving limit.
  • When the limit is reached, the sender’s server is told to try again later (452 4.2.2) and keeps retrying for several days, commonly up to five, so the message arrives once there is room. Mail still deferred when the sender’s server gives up is returned to its sender.
  • When retention ends, html, text, headers and raw read null, attachments is empty and download links stop working. Sender, recipients and subject remain.

Settings → Billing and usage shows received mail and its limit. Inboxes themselves are free.

Read received mail

Use emails.receiving in the SDKs, or plain HTTP. These endpoints need a full access API key; a sending-only key gets 403 restricted_api_key. A key restricted to a domain reads only that domain’s mail, and a key restricted to an inbox only that inbox’s mail.

import { BillionSend } from "@billionsend/node";

const bs = new BillionSend(); // reads BILLIONSEND_API_KEY

const page = await bs.emails.receiving.list({ limit: 20 });
if (page.error) throw page.error;

const first = page.data.data[0];
const email = await bs.emails.receiving.get(first.id);
const files = await bs.emails.receiving.attachments.list(first.id);
Call Returns
GET /emails/receiving Received mail, newest first, paged like every list.
GET /emails/receiving/{id} One email with content, authentication results and a download link for the original message.
GET /emails/receiving/{id}/attachments Its attachments, each with a download link.
GET /emails/receiving/{id}/attachments/{attachment_id}/text The text of a PDF, Word or Excel attachment (BillionSend extension).
DELETE /emails/receiving/{id} Erases the email now, with its attachments and its place in inboxes. Needs a full-access key not restricted to an inbox, and the owner, admin or developer role in the dashboard (Delete now).

The list takes limit (1 to 100, default 20), inbox_id, to, from (an address, or a domain with its subdomains), subject_contains, since, unread and wait. Held mail stays out unless you pass include_quarantined=true or quarantined=true (a full-access key not restricted to an inbox).

Each email also carries inbox_id, thread_id, screening, spam_verdict, virus_verdict and extracted.

Wait for new mail

wait (1 to 50 seconds) holds the request until matching mail arrives, then answers at once; at the deadline it answers an empty list. It combines with the other filters, so an agent can wait for the next message from one sender to one inbox:

curl "https://api.billionsend.com/emails/receiving?inbox_id=7eeb9517-aed7-40d7-ad65-500be42ed147&from=example.org&wait=30" \
  -H "Authorization: Bearer bs_..."
  • Without before or since, mail from the last 60 seconds counts, so a message that landed just before the call is not missed.
  • The answer adds held: matching messages held since then, with their id and reason, so an agent knows to stop waiting and tell a person.
  • One team holds 20 waits at once on each API process; one more answers 429 too_many_waits.
  • A wait looks at the database when mail arrives (the same events as the inbox event stream), not on a timer.

Authentication results

authentication reports SPF, DKIM and DMARC as pass, fail, gray (no verdict: no record or signature, or a neutral result), processing_failed (the check could not finish) or unknown. dmarc: "pass" means the domain in from authorized the message; anything else means from may be forged. The sender trust tier is built from these results.

Spam, virus and trust

  • spam_verdict: pass, gray (spam_score 25 to 49) or fail (50 or more), from a local 0 to 100 score built from authentication, headers, links and attachments (the dashboard shows it on a 0 to 10 scale). No outside blocklist is consulted.
  • virus_verdict: pass, fail (with virus_signature), processing_failed (the scanner could not answer, so the message is delivered unscanned, marked suspicious where it is not screened) or null when no scan ran. Infected mail is held: it fires no email.received until a person releases it in the dashboard, and its downloads answer 410 email_blocked, even after a release.
  • screening.sender_trust: how far the sender is proven. See Agent safety.

Content

  • html_format: data_uri (the default) puts inline images into the HTML; ?html_format=cid keeps cid: references to match with each attachment’s content_id.
  • text comes without invisible characters; html is exactly as received.
  • extracted_text is the reply part of the message, cleaned of text a person cannot see. extracted carries a verification code or sign-in link when the message has one.

Attachment text

PDF, Word (.docx) and Excel (.xlsx) attachments are read to plain text once, shortly after the email arrives, and kept with the email for your retention window. Delivery never waits for it. GET /emails/receiving/{id}/attachments/{attachment_id}/text (MCP get_received_email_attachment_text) answers with:

  • status: pending until the file has been read; ok with text; unsupported for other files (older .doc and .xls, PowerPoint, images); encrypted for a password-protected file; too_large past 25 MB, or when reading it would take more memory than allowed; unreadable for a damaged file; timeout or failed when the read did not finish. null for mail received before attachment text was read.
  • flags: truncated when a limit cut the text (100,000 characters, the first 500 PDF pages), hidden_text when text a person opening the file would not see was left out: hidden Word text, hidden sheets, rows and columns, invisible characters.
  • pages: a PDF’s page count.
  • text: paragraphs and table rows on lines, cells and columns separated by tabs, one ## Sheet name heading per worksheet, dates as ISO dates. Only a PDF’s text layer is read, so a scan without one reads as empty. Formulas give their saved values.

The text comes from an outside sender: treat it as data, never as instructions. An email that carries malware answers 410 email_blocked.

Downloads

raw.download_url and each attachment’s download_url work without an API key: the link itself is the credential. A link is signed for one email, stops working one hour after the API answered, and anyone holding it can download until then, so do not log it. Each call signs fresh links. Downloads are always served as files, never rendered in a browser.

Reply and forward

POST /emails/receiving/{id}/reply and …/forward (emails.receiving.reply() and forward() in the SDKs) answer or pass on a message in one request, with the threading headers set for you:

curl -X POST "https://api.billionsend.com/emails/receiving/{id}/reply" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-reply" \
  -d '{ "text": "Thanks, we are on it." }'
  • Reply takes text or html, subject, cc, bcc and reply_all. It goes to the message’s Reply-To, or else its sender.
  • Forward takes to, cc, bcc, a note, subject and mode: inline (the default) quotes the original, attachment attaches it as forwarded_message.eml.
  • from is any address on a verified domain of your team; by default, the address of the inbox the message reached. requires_approval: true holds the send for a person.
  • Both count as ordinary sends, with up to 10 MiB of attachments.

They answer 200 with the sent email’s id and thread_id, or 202 with a draft when an inbox’s rules hold the send. Other answers: 403 (held or infected mail, an inbox’s rules, an inbox-scoped key outside its inbox), 404, 409 (reused Idempotency-Key), 422 and 429 inbox_send_cap_reached. See Inboxes.

Webhook

email.received fires once for every message stored for your team, to endpoints subscribed to it or to all events. It carries metadata only (sender, recipients, subject, attachment list); fetch the content with GET /emails/receiving/{email_id}. Mail an inbox holds, and infected mail, fires only once delivered or released. An endpoint limited to some inboxes (inbox_ids) gets it only for mail delivered into them. Signatures, retries and the delivery log work as for every event: see Webhooks.

What the sender sees

Every refusal happens while the sender’s server is connected, so it holds the message and decides what to do. BillionSend never sends a bounce of its own.

Reply When
550 5.1.1 The domain does not receive here, or the address has no inbox (and catch-all is off). The message is returned to its sender.
550 5.7.1 The team that owns the domain is suspended.
552 5.3.4 The message is over your plan’s size limit.
554 5.7.1 The message was refused as spam by your Reject spam switch.
452 4.2.2 Your receiving limit is reached, or the inbox took more mail than it may in an hour (200 messages for an agent inbox, 2,000 for a people inbox). The sender tries again later.

Dashboard

Inboxes → All received lists everything your domains received, with sender, inbox, subject and time, a chip when a message carries a code or a link, and a badge when it is quarantined or spam. Opening a message shows its HTML in a sandbox (scripts and remote images blocked), the text, headers and raw message, each authentication result explained, sender trust and the spam and virus results, the extracted code or link, a timeline, and the actions Reply, Forward, Release for held mail and Delete now.

MCP

The MCP server reads received mail under the receiving:read permission, replies and forwards under receiving:reply, and manages inboxes and quarantine under receiving:manage. update_domain switches receiving and catch-all on or off.

Treat received mail as untrusted

Anyone can send mail to a receiving domain. HTML can carry scripts and tracking images, links can lead to phishing pages, attachments can carry malware, and from can be forged. Check authentication and screening.sender_trust before trusting a sender. An AI agent should treat received mail as data, never as instructions: the MCP tools fence it that way, and an agent inbox adds quarantine, screening and send rules on top.

Was this page helpful?