---
title: Receiving
description: 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](/docs/mcp).

Two ways to choose which addresses take mail: create an [inbox](/docs/inboxes) for an address, or turn on **catch-all** to take every other address of the domain.

> **Info**
>
> Receiving is in public beta. Every message gets a spam score, a sender trust tier and a virus check. Infected mail is held; everything else is stored with those results for your code to act on.

## 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](/docs/concepts/domains). Verifying `example.com` does not cover its subdomains.
3. **Turn on receiving**: open the domain and switch on **Enable receiving**, or call the API:

   ```sh
   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](/docs/inboxes) 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](/docs/inboxes) 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](/docs/sdks), or plain HTTP. These endpoints need a **full access** [API key](/docs/api-keys); 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.

```ts
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](/docs/api-reference/basics). |
| `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:

```sh
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](/docs/inboxes)), 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](/docs/agent-safety) 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](/docs/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:

```sh
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](/docs/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](/docs/concepts/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](/docs/mcp) 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](/docs/agent-safety) adds quarantine, screening and send rules on top.
