---
title: "Inbox"
description: "The inbox receives mail on your domains and lets a team read, sort and answer it."
url: https://onesend.email/docs/inbox/
---
# Inbox

The inbox receives mail on your domains and lets a team read, sort and answer it. Everything in it is also available through the API, the SDK, the `onesend` CLI and the MCP server, so the same mailboxes work for support teams and for automated tests that need a fresh address.

Mailboxes members own elsewhere (Gmail, Outlook, iCloud, Zoho, any IMAP server) can be connected too and show in the same inbox: see [Unified inbox](https://onesend.email/docs/unified-inbox/).

To receive mail, a domain needs inbound turned on and its ownership TXT record verified. See [Inbound mail options](https://onesend.email/docs/self-hosting/#receiving-mail) for the receivers, and [Try the inbox locally](https://onesend.email/docs/getting-started/#try-the-inbox-locally) to test on your own machine.

<a id="license-key"></a>
**License key.** The inbox, calendar, booking pages and drive are part of the self-hosted edition. On a server that needs a [license key](https://onesend.email/docs/self-hosting/#license-key), they are locked while it has no active key: the dashboard shows one card that points to **Settings → License**, and the endpoints below answer 402 `license_required`. Nothing is deleted, and mail sent to your mailboxes is still received and kept. See [Without a license key](https://onesend.email/docs/self-hosting/#workspace-without-a-license-key).

All endpoints below are under `/v1`. Test-mode API keys (`os_test_…`) cannot read or change the inbox; they can only reply and write new messages, which are logged and not delivered.

## Mailboxes

A mailbox is an address on one of your domains, such as `support@acme.dev`, or a catch-all (`*@acme.dev`) that receives every address on the domain that has no mailbox of its own.

```bash
curl -X POST http://localhost:3000/v1/inbox/mailboxes \
  -H "Authorization: Bearer $ONESEND_API_KEY" -H "Content-Type: application/json" \
  -d '{"domainId":"dom_…","localPart":"support","name":"Support","labels":["customers"],"metadata":{"team":"cx"}}'
```

| Field | Meaning |
|---|---|
| `localPart` | The part before `@`, or `*` for a catch-all. Omit it to get a random address such as `inbox-k3j9x2@acme.dev`. |
| `expiresAt` or `ttlSeconds` | Delete the mailbox at this time, or this many seconds after it is created (60 seconds to 365 days). |
| `deleteMessagesOnExpiry` | When the mailbox expires, also delete the mail it received. By default the mail is kept. |
| `metadata` | Your own JSON data (at most 4 KB), returned as is. |
| `labels` | Free-form strings for your own grouping. `GET /inbox/mailboxes?label=…` filters by them. |
| `autoCreate` | Catch-all only: mail to a new address creates a mailbox for that address. |
| `forwardTo` | Forward received mail to up to 10 addresses (see [Forwarding](#forwarding)). |
| `webhookUrl` | POST each received message to this URL (see [Webhooks](#webhooks)). |
| `domains` | Also receive the same local part on other domains of the workspace: a list of domain ids, `"all"` or `null` (only its own domain, the default). See [One mailbox on several domains](#one-mailbox-on-several-domains). |
| `access`, `accessUserIds`, `ownerUserId` | Who can read its mail: `workspace` (default), `members` or `personal`. See [Who can read a mailbox](#who-can-read-a-mailbox). |

Endpoints:

| Method | Path | Purpose |
|---|---|---|
| GET | `/inbox/mailboxes` | List, with unread counts. Filters: `domainId`, `label`, `q` (address contains). |
| POST | `/inbox/mailboxes` | Create one. A duplicate address returns 409 `mailbox_exists`. |
| POST | `/inbox/mailboxes/bulk` | Create up to 100: `{ "mailboxes": [ … ] }`. All are checked first; if one is not valid, none is created. |
| GET, PATCH, DELETE | `/inbox/mailboxes/{id}` | Read, update or delete. `DELETE …?deleteMessages=true` also deletes the mail it received. |
| GET | `/inbox/mailboxes/{id}/messages` | The mail one mailbox received. Takes the same filters as [search](#search). |
| POST | `/inbox/mailboxes/{id}/rotate-secret` | Replace the webhook signing secret. |

Each mailbox in a response also has `mappedAddresses` (the addresses on other domains it receives) and `canRead` (whether the caller may read its mail).

### Expiry

Expired mailboxes stop receiving mail at once and are deleted by a background job that runs every minute. Short-lived mailboxes suit end-to-end tests: create an address, sign up with it, read the confirmation email, and let it expire.

```ts
const box = await onesend.inbox.createMailbox({ domainId, ttlSeconds: 3600, deleteMessagesOnExpiry: true, labels: ['e2e'] });
// … sign up with box.address …
const [mail] = (await onesend.inbox.mailboxMessages(box.id)).data;
```

### Plus-addressing

Mail to `support+ticket-123@acme.dev` is delivered to `support@acme.dev` when no mailbox named `support+ticket-123` exists. The part after `+` is stored on the message as `plusTag` (`ticket-123`), shown in the dashboard and usable in search (`tag:ticket-123` or `?tag=ticket-123`) and in rules.

### Catch-all and auto-create

A catch-all receives mail for addresses without a mailbox. With `autoCreate: true`, the first message to a new address creates a mailbox for it (without the `+tag`), so each address gets its own list and unread count. Auto-created mailboxes copy the catch-all's labels and record `{"autoCreatedBy": "<catch-all id>"}` in `metadata`. Mail marked as spam never creates a mailbox, and a catch-all creates at most 1,000 mailboxes; after that mail goes to the catch-all. A workspace can have at most 10,000 mailboxes.

### One mailbox on several domains

A mailbox can receive its local part on several domains of the workspace, so `hello@acme.dev`, `hello@acme.io` and `hello@acme.co` all land in one mailbox: set `domains` to a list of domain ids, or to `"all"` for every domain of the workspace that receives mail, also domains added later. In the dashboard: **Inbox addresses → Settings → Also receive on**. The mailbox list shows the addresses it also receives.

```bash
curl -X PATCH http://localhost:3000/v1/inbox/mailboxes/mbx_… -H "Authorization: Bearer $ONESEND_API_KEY" -H "Content-Type: application/json" \
  -d '{"domains":["dom_io…","dom_co…"]}'
```

- **Which mailbox gets the mail.** On each recipient domain, in this order: a mailbox with that exact address (then the address without its `+tag`) on that domain; then a mailbox of another domain that maps this one (exact, then without `+tag`); then the domain's catch-all. So a mailbox of its own always wins over a mapped one, and a mapped one over the catch-all.
- **Only verified domains.** Every listed domain must be a domain of the workspace whose ownership it verified (the TXT record, as for [forwarding](#forwarding)); otherwise 400 `domain_not_verified`. At delivery the recipient domain must still be receiving (inbound on, ownership verified). A catch-all cannot map domains (400 `catch_all_not_mappable`).
- **No two mailboxes for one address.** Saving a mapping that another live mailbox with the same local part already has on a domain returns 409 `mailbox_exists`. `"all"` covers every domain, also future ones: two mailboxes with the same local part cannot both use `"all"`, and one using `"all"` conflicts with another listing any domain but the `"all"` mailbox's own.
- **Sending.** A mapped address works like an [alias](#signatures-and-aliases) of the mailbox, without adding one: it is listed by `GET /inbox/senders`, can be the `from` of the outbox and of `POST /inbox/compose` (with the mailbox's `mailboxId`), and replies to mail received on it go out from it. It cannot be added as an alias (400 `alias_is_mailbox`).

### Who can read a mailbox

`access` decides who reads a mailbox's mail:

| `access` | Who reads its mail |
|---|---|
| `workspace` (default) | Every member of the workspace, as before. |
| `members` | The members in `accessUserIds`, plus the workspace owners and admins. |
| `personal` | Only `ownerUserId` (default: the person who creates it). |

Owners and admins see personal mailboxes of other members listed (with `canRead: false` and no unread count) and can change their name, labels, expiry and mapped domains, and delete them; they cannot read their mail or make it forward mail or call a webhook (403 `personal_mailbox`): only its owner can. Deleting a `members` or `personal` mailbox always deletes its mail, drafts and scheduled messages: mail from it not sent yet (queued, scheduled, deferred, being sent) is canceled, and what was sent from it stays in the email log only as a delivery record, without its content or its stored source, so it never becomes visible to the whole workspace. When a member leaves the workspace they are taken off every `members` list; a personal mailbox they owned stays closed until an admin deletes it or gives it back (below).

**Who changes who reads a mailbox.** Of a `workspace` or `members` mailbox: an owner or admin, or the member who created it (403 `mailbox_access_admin_only` for anyone else), so a member cannot take a shared address away from the workspace by making it personal. Making a mailbox personal for someone else always needs an owner or admin. Of a personal mailbox: its owner. An owner or admin can also give a personal mailbox back (to `workspace`, to `members` with its owner on the list, 400 `owner_must_keep_access` otherwise, or to another member as its owner, never to themselves): the way back when someone took a shared address. They do it without reading the mail, but the new readers then read the mail it already has, so **its owner is told**: a system email to the owner (while they are a member) says who changed it and who reads it now, and the audit entry has `recovery: true`, `ownerUserId` and `ownerNotified`. Every change of who reads a mailbox is recorded in the audit log (`mailbox.access_changed`, with what it was and what it became). Personal calendars and My Drives have no such power: owners and admins cannot change who opens them (a personal calendar is not even listed for them; a My Drive can only be deleted).

**What owners and admins can do with personal mailboxes** without reading them: rename them, change their labels, expiry and mapped domains, delete them (with their mail), create an address again after deleting it, give them back (above), and set how long Trash and Spam are kept (`trashRetentionDays`, for every mailbox). Mail arriving for a deleted personal mailbox goes wherever the address leads then (another mailbox, a catch-all, or nowhere). A catch-all that is `members` or `personal` takes every address of its domain without a mailbox: creating a mailbox or mapping an address on that domain needs an owner or admin, or the owner of a personal catch-all (403 `domain_restricted`). Mailboxes a catch-all creates for new addresses (`autoCreate`) get the catch-all's `access`, `accessUserIds` and `ownerUserId`.

For everyone else, the mailbox and its mail do not exist: they get **404** (not 403, so nothing leaks), and its mail is left out of every list, search, count and feed. That covers the mailbox endpoints, messages, search, threads and their notes, unread and label counts, Important/Other, single messages, forwarded attachments, drafts, the outbox, Sent and `/v1/emails` (filtered in the query, so pages are never short; canceling answers 404 too), the event log `/v1/events` (received mail by its mailbox, sent mail by the mailbox it was sent from), bulk actions, Waiting for reply and reminders, subscriptions, sign-in codes, approvals, the stream and `/inbox/messages/wait`, the AI assistant (summaries, drafts, triage, Ask your inbox), MCP tools (they use these endpoints), mail apps (app passwords and IMAP/POP3/SMTP sign-in: an app password stops working when its owner loses access), the workspace data export and the export of one contact (`/v1/contacts/{id}/export`), which leave out mail of personal mailboxes and what is about it (its events, notes, follow-ups, subscriptions, imports, mail-app copies and spam filter). A conversation is assigned only to a member who can read it (400 `assignee_no_access`). Notes belong to the whole conversation: a conversation with mail the caller may not read shows no notes, and its notes answer 404.

Nothing about the mail of a `members` or `personal` mailbox goes to workspace webhooks or Slack and Discord channels: its received mail, the delivery events of mail sent from it, and messages from it held for approval are left out entirely (not sent with the sender and subject removed). The mailbox's own webhook, set by its owner, still gets its mail. The email about a message held for approval goes to the mailbox's `notifyUserIds`, or else the workspace owners and admins, who can read the mailbox: for a personal mailbox only its owner.

Sending from an address: a `from` that is the address of a mailbox the caller may not read is treated like an address without a mailbox (the same answers as any other address on the domain), and a duplicate address of such a mailbox answers 409 `mailbox_exists` with "This address is not available." and no details.

Mail the server sends for a mailbox belongs to it from its first event on (`mailboxId` on the message), so its `queued` and delivery events never reach workspace webhooks, chat channels or `/v1/emails` of people who cannot read it: compose, replies, the outbox, mail apps, the unsubscribe email of a subscription (sent from the mailbox that received the sender's mail; subscriptions of a mailbox the caller cannot read answer 404) and `POST /v1/emails/{id}/resend` of mail sent from a mailbox. A received message the mailbox (or a rule) forwards is sent as a copy that belongs to that mailbox: only the people who can read the mailbox see it (in the conversation, `/v1/emails`, the event log), and it is never in Sent or Waiting for reply. Copies forwarded before this have no mailbox: the inbox background job gives them theirs, and until then any sent message without a mailbox in a conversation of a mailbox the caller may not read is hidden like it.

Inbox rules on mail for a `members` or `personal` mailbox never move it into another mailbox, forward it or post it to a webhook. On a personal mailbox only the rules its owner made apply (the member who created a rule, or last changed what it matches or does, made it; also "archive future mail from this sender"). On a `members` mailbox, rules made by someone who cannot read it (not on the list, not an owner or admin, or an API key nobody is recorded for) still label and assign, but never drop, mark as spam or archive its mail.

Apps (MCP clients, OAuth apps) that count or empty Trash and Spam without naming a mailbox reach only the mailboxes whose own settings allow it (Inbox → AI and app access: Spam and Trash to count, also permanent deletion to empty); the workspace default decides for mail without a mailbox.

**API keys and apps** act with the rights of the member who created the key (or who connected the app), while that member is in the workspace; a live Admin key counts as an admin. A key nobody is recorded for reads only `workspace` mailboxes. Keys limited to some mailboxes (`mailboxIds`) are limited on top of that. So no key reads another member's personal mailbox.

## Rules

Rules run on every received message, in order (`position`), before it is stored. Each rule has conditions and actions.

```json
{
  "name": "Invoices to billing",
  "match": "any",
  "conditions": [
    { "field": "subject", "op": "contains", "value": "invoice" },
    { "field": "from", "op": "matches", "value": "*@billing.vendor.example" }
  ],
  "actions": [
    { "type": "deliver", "mailboxId": "mbx_…" },
    { "type": "label", "labelId": "lbl_…" }
  ],
  "stop": true
}
```

Conditions:

| Field | Compared with |
|---|---|
| `from` | The sender address, and the sender as written (`Name <a@b.com>`) |
| `to` | Each envelope recipient and each To and Cc address; the condition holds if any of them matches |
| `subject` | The subject |
| `header` | The header named in `header`, such as `X-Priority` (repeated headers are joined) |
| `plus_tag` | The plus-address tag |
| `has_attachment`, `spam` | `value: true` or `false` |

Operators for text fields: `contains`, `not_contains`, `equals`, `starts_with`, `ends_with` and `matches`, a glob where `*` is any text and `?` is one character. Comparisons ignore case. Regular expressions are not supported, so a rule cannot slow down mail delivery. `match: "all"` (default) needs every condition; `"any"` needs one. A rule with no conditions matches every message.

Actions:

| Action | Effect |
|---|---|
| `deliver` | Put the message in this mailbox. When several rules deliver, the first one wins. The mailbox's own outside forwarding and webhook apply to that mail only when an admin created or last changed the rule (`approvedForOutward`); otherwise the mail is only delivered there. |
| `label` | Add a label. |
| `assign` | Assign the conversation to a workspace member. |
| `forward` | Forward to up to 10 addresses, with the same safeguards as mailbox forwarding. Only addresses on a domain whose ownership the workspace verified (and its subdomains) count as inside the workspace; any other address, a connected mailbox's address included, must confirm first: it gets an email with a link, and nothing is forwarded to it until its owner clicks it (the rule shows **Waiting for confirmation**, `pendingConfirmation` in the API). See [Forwarding](#forwarding). |
| `webhook` | POST the message to a public URL, signed with the rule's secret. At most 3 per rule. |
| `mark_spam` | Store the message in Spam. |
| `archive` | Store the message in Archive instead of the inbox. |
| `drop` | Do not store the message at all. Later rules do not run. |

A rule that sends mail out of the workspace (an outside forward address, a webhook, or a `deliver` into a mailbox that forwards outside or calls a webhook, also while that mailbox's forwarding is turned off) needs a signed-in admin or owner, or a live `admin` API key (403 otherwise); a Full access key may still turn it off or rename it. The workspace owners get a security alert when one is created or gets a new destination. A rule like that is turned off when the API key that created it is revoked or reported as leaked (`disabledReason`: `key_revoked`, `key_leaked`), or when the member who set it up leaves the workspace (`member_removed`); turning it back on (**Turn back on**, `enabled: true`) needs an admin and alerts the owners again.

`stop: true` skips the rules after this one when it matches.

| Method | Path | Purpose |
|---|---|---|
| GET, POST | `/inbox/rules` | List in order, create. A rule with a webhook action returns `webhookSecret` once. |
| GET, PATCH, DELETE | `/inbox/rules/{id}` | Read, update, delete. |
| POST | `/inbox/rules/reorder` | `{ "ids": [ … ] }`: the listed rules first, in this order. |
| POST | `/inbox/rules/test` | Dry run. Nothing is stored, forwarded or sent. |
| POST | `/inbox/rules/{id}/rotate-secret` | Replace the webhook signing secret. |

Test rules with a sample message, or against a message you received (`messageId`; headers are not stored, so header conditions see none). Pass `rules` to test unsaved rules:

```bash
curl -X POST http://localhost:3000/v1/inbox/rules/test -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"message":{"from":"ap@vendor.example","to":["support+acct-9@acme.dev"],"subject":"Invoice 2026-11"}}'
```

The response lists the rules that matched and the combined outcome (`drop`, `spam`, `mailboxId`, `labels`, `assignTo`, `forwardTo`, `webhooks`) and the `plusTag`.

## Team inbox

The dashboard's **Inbox** shows every mailbox together or one at a time, with these views: Inbox (split into [Important and Other](#important-and-other)), Assigned to me, Unassigned, Starred, Snoozed, [Waiting for reply](#waiting-for-reply-and-follow-ups), [Scheduled](#undo-send-and-send-later), [Sign-in codes](#sign-in-codes), Drafts, Sent, Archive, Spam and Trash. Read status is shared by the workspace.

### Messages and conversations

| Method | Path | Purpose |
|---|---|---|
| GET | `/inbox/messages` | List and search (see [Search](#search)). |
| GET | `/inbox/messages/{id}` | Read one; marks it read unless `?markRead=false`. |
| PATCH | `/inbox/messages/{id}` | `read`, `starred`, `folder` (`inbox`, `archive`, `spam`, `trash`), `snoozedUntil`, `assignedTo`, `addLabels`, `removeLabels`, `report` (`spam`, `not_spam`: see [Spam filter](#spam-filter)). |
| POST | `/inbox/messages/{id}/report-spam`, `/inbox/messages/{id}/not-spam` | Report spam or not spam (the same as PATCH with `report`). |
| POST | `/inbox/messages/{id}/reply` | Reply in the conversation, from the address that received it. |
| GET | `/inbox/threads/{threadId}` | The conversation: received and sent messages in order, with delivery attempts for sent ones, notes, labels and the assignee. |
| PATCH | `/inbox/threads/{threadId}` | The same fields as a message, applied to every received message in the conversation. |

- **Conversations:** a received message joins the conversation its `In-Reply-To` / `References` point to only when that conversation is in the same mailbox (mail without a mailbox: only mail without a mailbox). Knowing a Message-ID is not enough to add mail to another mailbox's conversation, or to read its notes. [Imported mail](#importing-mail) only forms conversations within its own import.
- **Snooze:** `snoozedUntil` hides a message from the inbox until that time. A background job then shows it again as unread. `null` removes the snooze.
- **Assignment:** `assignedTo` is a workspace member's user id or email, `me` (dashboard sessions only) or `null`. New messages in an assigned conversation keep the assignee. `GET /inbox/members` lists members.
- **Labels:** `GET/POST /inbox/labels`, `PATCH/DELETE /inbox/labels/{id}` (`name`, `color` such as `#2563EB`). `addLabels` and `removeLabels` take ids or names. Deleting a label removes it from messages and rules.

### New messages, drafts and Sent

`POST /inbox/compose` sends a new message from one of your mailbox addresses (`mailboxId`, or `from` set to a mailbox address; for a catch-all, give both). It goes through your routing policy like any email, starts a conversation, and replies to it arrive in the same conversation. New messages and replies from the inbox are limited to 30 at once per workspace, then one every 2 seconds (429 with `Retry-After`).

**Attachments.** `POST /inbox/compose`, `POST /inbox/messages/{id}/reply` and the outbox take `attachments`: up to 20 files, each `{ "filename": "report.pdf", "contentType": "application/pdf", "content": "<base64>" }` (`size`, when given, must match), or `{ "fromMessageId": "inb_…", "index": 0 }` to forward a file of a received message you can read. Together at most 25 MB (`ONESEND_INBOX_ATTACHMENTS_MAX_MB`; 413 `attachments_too_large`); from a mailbox address, which sends through your providers, each file is at most 10 MB, as with `POST /v1/emails` (400 `attachment_too_large`). They are stored with the sent copy in the same format as `POST /v1/emails` attachments, encrypted at rest and removed after the retention period like other message bodies. Connected accounts send them in the message itself (SMTP, Gmail API raw MIME, Microsoft Graph: MIME up to its 4 MB request limit, above that a draft with file attachments and upload sessions; Zoho Mail API: uploaded first). Messages held for approval (agent send policies) cannot carry attachments (400 `attachments_need_approval`).

Drafts: `GET/POST /inbox/drafts`, `GET/PATCH/DELETE /inbox/drafts/{id}`, and `POST /inbox/drafts/{id}/send`. A draft with `replyToId` is sent as a reply in that conversation; otherwise as a new message. `GET /inbox/drafts?mine=true` lists the signed-in user's drafts.

Sent: `GET /inbox/sent` lists replies and new messages written from the inbox (filter by `mailbox` or `q`). `GET /inbox/sent/{id}` adds the body and each delivery attempt: provider, connection, result, error code and message, and time.

### Internal notes

`GET/POST /inbox/threads/{threadId}/notes` (`{ "body": "…" }`) and `DELETE /inbox/notes/{id}`. Notes are shown in the conversation to your team and are never sent.

### Look-alike senders

When the From domain of a received message looks like one of your domains or a domain you have sent email to, the message gets a `lookalike` field and the dashboard shows a warning above it. A domain counts as a look-alike when, after decoding punycode (`xn--…`), it:

- uses characters that look like the known domain's (`аcme.dev` with a Cyrillic `а`, `acrne.dev`, `inb0x.dev`), or
- is within 2 edits of a known domain of 8 or more characters, or 1 edit of one with 5 to 7 characters.

Your own domains, subdomains of known domains and the known domains themselves are never flagged. The check is a hint, not a block: the message is delivered as usual. The [spam filter](#spam-filter) counts it as a strong signal.

## Spam filter

Mail received on your domains (built-in receiver, Cloudflare Email Worker, provider inbound webhooks) gets a spam score from 0 to 100, worked out on your server. Nothing about the message is looked up on the network or sent anywhere.

| Score | Where it goes |
|---|---|
| 70 or more | Spam |
| 40 to 69 | Where it would go anyway, marked `suspicious` (the dashboard shows a **Suspicious** badge and the reasons) |
| below 40 | Where it would go anyway |

**Signals.** Each adds or removes points:

- **Sender authentication**: SPF, DKIM and DMARC results from your own receiver (`Authentication-Results` the sender wrote are ignored). Failing raises the score. Passing lowers it only when it is for the From domain: DMARC passed, or SPF passed with an aligned `smtp.mailfrom`, or DKIM passed with an aligned `header.d` (relaxed alignment: the same registrable domain). A pass for some other domain lowers nothing.
- **Relationship**: a reply in a conversation you wrote in, an address you have written to, a domain you send to (not free mail providers such as gmail.com) and your own domains lower it, but only for mail whose From domain authenticated as above. Anyone can write a known address in From or quote one of your Message-IDs, so forged mail gets no credit for it. A sender never seen before raises it a little; a [look-alike](#look-alike-senders) domain, or mail claiming to be from your own domain that fails authentication, raises it a lot. Mail without such a result gets no relationship credit: a receiver that does not check SPF and DKIM, or a provider webhook that reports SPF or DKIM without the domain they passed for and no DMARC result (provider webhooks that report DMARC, such as Amazon SES and Resend, count by their DMARC pass).
- **What your team reported**: each mailbox has its own naive Bayes model of the words in subjects and bodies and the domains linked to, trained only by **Report spam** and **Not spam**. Words are stored as 32-bit keyed hashes (HMAC-SHA256 under a key derived from `ONESEND_SECRET` for each workspace), never as text, so a copy of a model (a database dump, a workspace export) cannot be matched against a word list without the server secret. A model keeps at most 20,000 tokens (the least recently trained go first) and halves its counts past 4,000 trained messages, so it stays under about 0.5 MB and follows what your mail looks like now. Models trained before this key existed (before migration 0043) were deleted by the migration and start again from the next report; a model made under another key (after `ONESEND_SECRET` is changed) is not used and starts again the same way.
- **Links**: to a bare IP address; link text showing one domain while the link goes to another (`www.paypal.com` linking elsewhere); punycode (`xn--`) hosts; more than 10 different link domains; known link shorteners.
- **Structure**: HTML-only mail with hidden text, a subject in capitals, mostly images and little text.
- **Attachments**: programs and scripts (`.exe`, `.js`, `.vbs`, `.iso`, `.lnk` and similar), double extensions (`invoice.pdf.exe`), Office files with macros (`.docm`, `.xlsm`), and password-protected archives (an encrypted ZIP, or an archive with a password mentioned).

**Hostile mail.** Anyone can send mail, so the filter's work per message is bounded: it reads at most the first 150 KB of the HTML (with a single-pass tag reader, not regular expressions that can backtrack) and of the plain text, the first 60,000 characters for words, and at most 500 links. A crafted message of several megabytes (unclosed tags, comments or scripts) is scored in a few milliseconds.

Up to 3 reasons (the signals that added the most) are kept with the message: `spamReasons` in the message JSON, with `spamScore`, `suspicious` and `spamReport` (what someone reported it as). Codes: `new_sender`, `lookalike`, `own_domain_spoof`, `auth_failed`, `dmarc_failed`, `content`, `link_mismatch`, `ip_link`, `punycode_link`, `many_link_domains`, `shortener`, `hidden_text`, `caps_subject`, `image_heavy`, `executable`, `double_extension`, `macro`, `encrypted_archive`, and `header` or `rule` for mail that went to Spam for those.

**Rules and the upstream flag.** An upstream `X-Spam-Flag: YES` and a rule's `mark_spam` still put mail in Spam, scored or not. A rule's `drop` still drops it before anything is scored. A matching rule that explicitly places the mail (`deliver` or `archive`) wins over the score: it goes where the rule says, marked `suspicious`, so an admin's rule for a sender the filter dislikes keeps working. The rule condition `spam` means the upstream flag (rules run before the score).

**Spam stays quiet.** Mail stored in Spam is not forwarded, calls no mailbox webhook and no rule webhook (except rules with a `spam` condition, written for spam), sends no `received` workspace webhook or chat notification, and is not shown to agents in `GET /inbox/stream`, long polls or MCP notifications.

**Report spam and Not spam.** `POST /inbox/messages/{id}/report-spam` moves a message to Spam and trains its mailbox's model; `POST /inbox/messages/{id}/not-spam` moves it out of Spam (to the inbox, or to `folder` given with PATCH) and clears `suspicious`. The same is `report` on `PATCH /inbox/messages/{id}`, `PATCH /inbox/threads/{threadId}` (every received message in the conversation) and `POST /inbox/bulk`. Each message remembers what it was trained as: reporting it the other way later takes the earlier training back first, and reporting it the same way again changes nothing. One report trains at most 50 messages of each mailbox (the rest are moved but not trained, and can be reported again), so a bulk report cannot rewrite a mailbox's model at once. Only these reports train the filter (moving mail between folders does not), and keys limited to some mailboxes cannot report. In a mail app (IMAP), moving a message into Junk is Report spam, and moving it from Junk to the inbox, Archive or a label is Not spam; moving it to Trash teaches nothing. Deleting a mailbox deletes its model.

**Turning it off.** The **Spam filter** switch (Inbox → Signatures and aliases), or `PATCH /inbox/settings/*` with `{ "spamFilter": false }` (a workspace setting; on by default, `null` returns to the default). Off, new mail is not scored; mail already received stays where it is. Other server processes notice within a minute.

**Cost.** Per received message the filter reads the workspace setting and the mailbox's model, each cached in memory (1 and 10 minutes, at most 500 models), so it adds at most two database statements and usually none. Near the per-invocation statement budget (Cloudflare D1) it scores without the model. A report makes one read and one write of each mailbox's model, however many messages it covers. If scoring fails, the message is delivered as if the filter were off.

Mail of [connected accounts](https://onesend.email/docs/unified-inbox/) is not scored here: their own provider filters it, and their spam arrives in Spam. Report spam and Not spam still train a model for the account and move the message there too.

## Trash and Spam

**Empty.** `GET /inbox/folders/{trash|spam}/count?mailbox=…` says how many messages are there; `POST /inbox/folders/{trash|spam}/empty` with `{ "mailboxId": "mbx_…" }` (or nothing, for every mailbox you can read and mail without a mailbox) deletes them permanently, with their stored source and files. One call deletes at most 1,000 messages and returns `{ "deleted": …, "remaining": … }`; call again until `remaining` is 0. The dashboard shows **Empty Trash** and **Empty Spam** above those views (in the Mac app, **Empty Trash** and **Empty Junk**), with the count in the confirmation. Mail of connected accounts is not counted or deleted: their own server keeps their Trash and Spam, and the confirmation says so when accounts are connected. Apps need `allowPermanentDelete` and `showSpamTrash` ([AI and app access](#ai-and-app-access)); test-mode keys cannot.

**Auto-delete.** The workspace setting `trashRetentionDays` (1 to 365, `null` to keep; `PATCH /inbox/settings/*`, or **Inbox settings → Trash and Spam**) deletes mail that has been in Trash or Spam for that many days, counted from when it was moved there: in the dashboard, by the API (also `report: "spam"`, bulk actions), by a mail app (Trash, Junk), or, for mail received straight into Spam (a rule's `mark_spam`, the spam filter), from when it arrived. The inbox sweep job does it every minute, a few chunks at a time (within Cloudflare D1's statement limits). Mail of connected accounts is not touched by either: its Trash and Spam follow the account's own server.

## Search

`GET /inbox/messages` searches the subject, sender, recipients, preview and body. Query parameters: `q`, `folder` (`inbox` by default, `archive`, `spam`, `trash`, `snoozed`, or `all`), `mailbox`, `label` (id or name), `tag`, `assigned` (`me`, `none`, `any` or a user id), `unread`, `starred`, `hasAttachment`, `after`, `before`, `cursor` and `limit`.

`q` also takes operators. Words without an operator must all appear; quotes keep spaces together.

| Operator | Example |
|---|---|
| `from:` `to:` `subject:` | `from:ann subject:"order 7781"` |
| `label:` | `label:billing` or `label:"Hot lead"` |
| `mailbox:` | `mailbox:support@acme.dev` |
| `tag:` | `tag:ticket-123` |
| `is:` | `is:unread`, `is:read`, `is:starred`, `is:snoozed`, `is:assigned`, `is:unassigned` |
| `assigned:` | `assigned:me` |
| `has:attachment` | |
| `in:` | `in:archive`, `in:all` |
| `before:` `after:` | `after:2026-11-01 before:2026-11-08` |

## Forwarding

A mailbox (`forwardTo`) or a rule (`forward`) can forward received mail to up to 10 addresses. It is sent through your providers from the receiving address, with the original sender as Reply-To. Mail marked as spam, mail that fails both SPF and DKIM, mail over 10 MB and mail OneSend already forwarded is kept in the inbox but not forwarded.

**Inside and outside.** Only addresses on a domain whose ownership the workspace verified (the TXT record), and its subdomains, are inside the workspace. Everything else is outside, including the address of a connected mailbox (a member can connect a mailbox anywhere). Which addresses are outside is worked out again for every message, so an address whose domain loses its verification needs confirming before it gets mail again.

**Admins only.** Forwarding to an outside address, or a webhook, on a mailbox or a rule needs a signed-in admin or owner, or a live `admin` API key (403 otherwise). So does a rule that delivers into such a mailbox. The workspace owners get a security alert, which for a mailbox also lists the inbox rules that route mail into it. Mail a `deliver` rule routes into a mailbox is forwarded outside, or sent to the mailbox's webhook, only when an admin created or last changed that rule (`approvedForOutward`); a rule saved by a member while the mailbox did not forward outside keeps its mail in the mailbox.

**Confirmation.** Each outside address gets an email with a link and receives nothing until its owner opens it and confirms (**Waiting for confirmation**, `pendingConfirmation`). A link works once, for 14 days; after that the page says it expired, and saving the rule or the mailbox's `forwardTo` again sends a new link. Mailboxes that forwarded before confirmations existed keep forwarding to the addresses they had.

**Turned off, and back on.** Forwarding, webhooks and rules that send mail out stop when the API key that set them is revoked or reported as leaked, or when the member who set them leaves the workspace (`forwardingDisabledReason` on a mailbox, `disabledReason` on a rule). While turned off, confirmation links are refused. They stay off until an admin turns them back on explicitly: **Turn back on** in the dashboard, `enabled: true` on a rule, or `POST /v1/inbox/mailboxes/{id}/forwarding/enable` on a mailbox. Saving the mailbox again does not: removing its webhook leaves its forwarding off, and the other way round. Turning back on makes the admin who did it the one who set it up, and alerts the owners with every destination turned back on.

## Webhooks

A mailbox with `webhookUrl`, and a rule with a `webhook` action, POST each received message as JSON (mail stored in Spam is left out: see [Spam filter](#spam-filter)):

```json
{ "type": "email.received", "data": { "id": "inb_…", "threadId": "thr_…", "mailboxId": "mbx_…", "from": "…", "to": ["…"], "subject": "…", "text": "…", "html": "…", "plusTag": null, "labels": [], "receivedAt": "…" } }
```

Deliveries are signed like [outgoing webhooks](https://onesend.email/docs/webhooks/): `X-OneSend-Signature: v1=hex(hmac_sha256(secret, timestamp + "." + body))` with `X-OneSend-Timestamp`. The secret is random, returned once when the mailbox or rule is created (or when a webhook is first added), stored encrypted, and kept when `ONESEND_SECRET` is rotated. Replace it with `rotate-secret`. URLs must be public: private and internal addresses are refused.

## Important and Other

Received mail is sorted when it arrives, because headers are read only then:

- **Important:** mail from people. Senders you have written to from the inbox, replies in conversations you started, direct mail without bulk headers, and security alerts or sign-in notices (even from a no-reply address).
- **Other:** bulk mail. Messages with `List-Unsubscribe`, `List-Id` or `Precedence: bulk`/`list` headers, no-reply senders, newsletters and receipts.

Each message has `category` (`important` or `other`) and `categoryReason` (`override`, `security`, `reply`, `correspondent`, `direct`, `list_headers`, `bulk_precedence`, `noreply`, `newsletter`, `receipt`). Mail received before sorting existed has `category: null` and is shown under Important.

| Method | Path | Purpose |
|---|---|---|
| GET | `/inbox/categories/{important\|other}/messages` | The same filters as [search](#search). |
| GET | `/inbox/categories` | Unread counts of each. |
| POST | `/inbox/categories/move` | `{ "messageIds": [ … ], "category": "other", "alwaysForSender": true, "match": "domain" }` moves messages, and with `alwaysForSender` remembers the sender. |
| GET, POST | `/inbox/sender-rules` | "Always important/other from this sender": `{ "sender": "ann@x.com" or "x.com", "category": "important", "scopeId": "mbx_…" }`. Mail already received from the sender is moved too. |
| DELETE | `/inbox/sender-rules/{id}` | Remove an override. |

Sender rules follow [mailbox access](#who-can-read-a-mailbox): a rule for one mailbox or account needs its mail to be readable by you (404 otherwise), and only the rules you can read are listed or removable. Mail of a **personal** mailbox (or a private connected account) follows only the rules its owner made: a rule another member makes for every mailbox (`*`) leaves it alone, for new mail and for mail already received, and a rule for every mailbox never moves mail of mailboxes its author may not read.

The split is on for every mailbox by default. Turn it off for a mailbox or account with `PATCH /inbox/settings/{scopeId}` `{ "split": false }` (or `*` for the workspace default): all its mail is then under Important. The dashboard shows Important, Other and Everything as tabs in the Inbox view.

## Waiting for reply and follow-ups

**Waiting for reply** lists conversations where the last message is one you sent from the inbox (a new message, a reply or a follow-up) at least N days ago (3 by default, your preference `waitingDays`) and nobody has answered.

| Method | Path | Purpose |
|---|---|---|
| GET | `/inbox/waiting?days=3&mailbox=…` | Waiting conversations with any reminder. |
| POST | `/inbox/waiting/{threadId}/dismiss` | Stop showing it until you send in it again. |
| POST | `/inbox/followups` | `{ "threadId": "thr_…", "remindAt": "…" }`. At that time, unless someone replied, the conversation's received mail returns to the inbox (unread) and the reminder is listed as due. |
| GET | `/inbox/followups?status=due` | Reminders (`scheduled`, `due`, `done`, `canceled`, `all`). |
| POST, DELETE | `/inbox/followups/{id}/done`, `/inbox/followups/{id}` | Mark done, cancel. |
| POST | `/inbox/waiting/{threadId}/follow-up-draft` | A suggested follow-up. Written by the [AI assistant](https://onesend.email/docs/ai/) when it is on (from the conversation, with codes redacted as for any AI use), else from a short template. Nothing is sent: send it with the outbox and `followUpOf`, and it goes in the same conversation. |

## Undo send and send later

New messages and replies written in the dashboard go through the **outbox**. Nothing reaches your providers until the send time, so a message can be canceled until then.

- **Undo send:** messages wait for your undo delay (preference `undoSendSeconds`: 0 for off, or 5 to 30 seconds, default 10). The dashboard shows **Undo** while they wait; undoing opens the message again.
- **Send later:** pick a time (up to a year ahead). Scheduled messages are listed in the **Scheduled** view, where you can edit the text or the time, send now or cancel.

| Method | Path | Purpose |
|---|---|---|
| POST | `/inbox/outbox` | `{ "mailboxId": "mbx_…", "to": [ … ], "subject": "…", "text": "…" }`, or `replyToId` for a reply, or `followUpOf` (a sent message id) for a follow-up. `sendAt` schedules it; `delaySeconds` overrides the undo delay. `signature: false` leaves the signature out; `quote: false` leaves the quoted message out of a reply. |
| GET | `/inbox/outbox?status=scheduled` | Scheduled messages (`sending`, `sent`, `canceled`, `failed`, `all`). |
| GET, PATCH | `/inbox/outbox/{id}` | Read; change `to`, `cc`, `subject`, `text`, `sendAt` or `attachments` (the new list replaces the old) while it is scheduled. `attachments` in the response lists names, types and sizes, never the content. While a message waits, its files are stored encrypted; once sent they live with the sent copy. |
| POST | `/inbox/outbox/{id}/cancel` | Undo. 409 `too_late` once it was sent. Returns the message, with what you wrote in `original`. Attachment content is dropped (names, types and sizes stay in `attachments`). |
| POST | `/inbox/outbox/{id}/send-now` | Send it now. |

The outbox is for people signed in to the dashboard (403 `session_required` for API keys); keys and apps keep using `POST /inbox/compose` and `/reply`. A scheduled message is sent as the person who wrote it, if they are still a member who can send.

## Signatures and aliases

**Signatures** are written as rich text in the dashboard (bold, italic, links, lists, `https` images; everything else is removed) and stored as HTML plus a plain-text version. The signature added to a message is the first default that fits: the one for the exact sending address, the one for the mailbox or account, then the workspace one. In replies it goes above the quoted text (default) or below it, a per-mailbox setting (`signaturePlacement`).

| Method | Path | Purpose |
|---|---|---|
| GET, POST | `/inbox/signatures` | `{ "name": "Support", "html": "<b>Support</b> at Acme", "scopeId": "mbx_…", "address": null, "isDefault": true }`. Or `text` only. |
| PATCH, DELETE | `/inbox/signatures/{id}` | Change, delete. One default per mailbox and address. |

**Aliases** are other addresses and sender names you can send from in a mailbox, such as `Acme Help <help@acme.dev>` in `support@acme.dev`. An alias must be on one of your verified domains, or be an address the connected account may send as (its own address, or one in the account's `config.aliases`); otherwise 400 `alias_not_verified`. An address that is already a mailbox cannot be an alias. An alias can name its own signature.

| Method | Path | Purpose |
|---|---|---|
| GET, POST | `/inbox/aliases` | `{ "scopeId": "mbx_…", "address": "help@acme.dev", "name": "Acme Help", "signatureId": null }` (workspace admins). |
| PATCH, DELETE | `/inbox/aliases/{id}` | Change the name or signature; remove. |
| GET | `/inbox/senders?mailboxId=…` | Every address you can send from, with its default signature. |

Send from an alias with the outbox: `{ "mailboxId": "mbx_…", "from": "help@acme.dev", … }`.

## Subscriptions

Senders of bulk mail (newsletters, mailing lists, notifications) are listed under **Inbox → Subscriptions** with how many messages they sent, when one was last opened, whether any was ever opened, and how to leave:

- **One click:** when the mail had `List-Unsubscribe` with an `https` URL and `List-Unsubscribe-Post: List-Unsubscribe=One-Click` (RFC 8058), OneSend sends `POST` with the body `List-Unsubscribe=One-Click` to that URL. Private and internal addresses are refused.
- **By email:** a `mailto:` address gets an email (with the subject and body from the link) sent through your providers from the address that received the mail.
- **Link:** otherwise the sender's page opens for you to finish.

**Archive** moves what the sender already sent out of the inbox; **archive future mail** also creates an inbox rule (`from` equals the sender, action `archive`) so new mail goes straight to Archive.

| Method | Path | Purpose |
|---|---|---|
| GET | `/inbox/subscriptions?status=subscribed` | Bulk senders with `count`, `lastReadAt`, `neverOpened`, `inInbox` and `unsubscribe.methods`. |
| POST | `/inbox/subscriptions/{id}/unsubscribe` | `{ "method": "one_click" \| "mailto" \| "link" }` (default: the best one offered). |
| POST | `/inbox/subscriptions/{id}/archive` | `{ "future": true }` also archives future mail. |
| DELETE | `/inbox/subscriptions/{id}/auto-archive` | Stop archiving future mail (deletes the rule). |

Rules have an `archive` action for the same purpose.

## Sign-in codes

The **Sign-in codes** view lists one-time codes and sign-in links from mail received in the last 24 hours, found the same way as in the [agent view](https://onesend.email/docs/agent-inbox/), with copy buttons. `GET /inbox/codes?hours=24` returns them for people signed in to the dashboard only; API keys, apps and MCP clients get 403 and see codes redacted unless a mailbox allows them (next section).

## AI and app access

**Inbox → AI and app access** sets, per mailbox or connected account (and a workspace default), what the AI assistant, MCP clients (the local `onesend-mcp` server and the remote `/mcp` endpoint), OAuth apps and agent views may see and do. People in the dashboard and plain API calls are not affected.

| Setting | Default | Effect |
|---|---|---|
| `ai` | on | The AI assistant may read this mail (summaries, reply drafts, triage, Ask your inbox, follow-up drafts). |
| `mcp` | `full` | Apps: `full`, `read_only` (no changes, notes, drafts or sending) or `off` (the mailbox is hidden). |
| `mcpSend` | off | Apps may send through MCP (reply, compose, send drafts, and `POST /emails` from the mailbox's address). Otherwise 403 `mcp_send_disabled`. |
| `showSpamTrash` | off | Spam and Trash are visible. Otherwise they are left out of lists and answer 404. |
| `showCodes` | off | One-time codes and sign-in links are shown. Otherwise they are replaced with `[code hidden]` and `[sign-in link hidden]` in messages, conversations and agent views (`codes` is empty and `redacted` says what was removed), and in what the AI assistant reads. |
| `allowPermanentDelete` | off | Apps may delete mail permanently (`DELETE /inbox/mailboxes/{id}?deleteMessages=true`). Otherwise 403 `permanent_delete_blocked`; moving to Trash still works. |

Agent mailboxes (created with `POST /v1/agent/mailboxes`, which adds the `agent` label) start with `mcpSend` and `showCodes` on, because they exist for an agent; their send policy still applies.

`GET /inbox/settings` returns every mailbox's resolved settings; `PATCH /inbox/settings/{scopeId}` (`*` for the workspace) changes them: `{ "access": { "mcpSend": true } }`, `null` for a field returns it to the default. Only workspace admins in the dashboard can change these settings; API keys and apps get 403.

Requests are treated as coming from an app when they carry `X-OneSend-Source: mcp` (both MCP servers send it), use an OAuth access token, or ask for an agent view (`view=agent`, `/inbox/messages/wait`). A full-access API key used directly is the API, not an app: limit what such keys can reach with [mailbox-scoped keys](https://onesend.email/docs/agent-inbox/).

## Bulk actions, layout and shortcuts

`POST /inbox/bulk` applies one change (the fields of `PATCH /inbox/messages/{id}`) to up to 500 messages or 200 conversations: `{ "messageIds": [ … ], "threadIds": [ … ], "patch": { "folder": "archive" } }`.

Your preferences (`GET/PATCH /inbox/preferences`) hold the undo delay, waiting days, row density (`comfortable`, `compact`), layout (`split`: list and reader side by side; `list`: a wide list with checkboxes for bulk actions), and keyboard shortcuts: a preset (`standard`, the dashboard's own keys; `webmail` and `classic`, modeled on common web mail and desktop mail conventions) plus your own keys per action (`shortcuts: { "archive": "y" }`, `null` to reset). Press `?` in the inbox to see and change them.

<a id="importing-mail"></a>
## Importing mail

Bring old mail into a mailbox (one of your addresses) or a connected account from files: `.eml` files (one message each) and `.mbox` files (many). That covers a Gmail Takeout (`All mail Including Spam and Trash.mbox`), a mailbox exported from Apple Mail (**Mailbox → Export Mailbox…** saves a folder `Name.mbox` with a file named `mbox` inside) and Thunderbird. In the dashboard: **Import mail…** in the Inbox sidebar or on **Addresses**; choose or drop the files (folders too), the mailbox, the folder, and follow the progress. In the Mac app also **File → Import Mail…** and **File → Import from Apple Mail…** (see Mac app).

Imported mail is history, so it is stored like received mail (threads, attachments, the source for mail apps, encryption at rest, Important/Other) but:

- no [rules](#rules), forwarding, webhooks, agent events or notifications run, and nothing is sent;
- the original `Date` is kept (else the mbox `From ` line's date);
- read and flagged state come from the export when it has it (`keepFlags`, on by default): Gmail's `X-Gmail-Labels` (`Unread`, `Starred`), `Status` (`R` read), `X-Status` (`F` flagged) and Thunderbird's `X-Mozilla-Status`. Messages without them are imported as read;
- Gmail Takeout messages labeled Spam or Trash go to those folders, and, when importing into the inbox, messages without the Inbox label go to Archive (as in Gmail). With `labels: true` the person's own Gmail labels become inbox labels of the same name (missing ones are created; Gmail's system labels and categories are not copied; at most 200 labels per workspace);
- a message already in that mailbox or account (the same Message-ID) is skipped, so importing the same file again is safe. A message without a Message-ID gets one derived from its content (`<…@import.onesend.invalid>`), so it is not imported twice either;
- it is marked as imported: `imported: true` and `importId` in the message JSON, and an **Imported** badge in the message list and above the message. Its sender, date and headers are what the file says, unverified;
- conversations are formed only within the same import (its messages' `In-Reply-To` / `References` between each other). An imported message never joins a conversation that existed before the import, one of another import, or one in another mailbox, and nothing outside the import is changed;
- imported mail is never evidence for anything else: it is not scored by the spam filter or used to train it (until someone reports it), and it does not make a sender a known correspondent or a reply in your conversations for Important/Other or the spam filter.

Messages larger than 25 MB, and files that are not mail (a message must start with a header line such as `From:`; anything else is `not_a_message` without being parsed), are counted as failed; the import goes on. Imports into a connected account are stored here only: nothing is uploaded to the account.

| Method | Path | Purpose |
|---|---|---|
| POST | `/inbox/imports` | `{ "mailboxId": "mbx_…" or "accountId": "acc_…", "folder": "inbox", "labels": false, "keepFlags": true, "files": [{ "name": "Takeout.mbox", "size": 123456789 }] }`. Returns the import with each file's `chunkSize` (8 MiB) and `totalChunks`. |
| PUT | `/inbox/imports/{id}/files/{index}/chunks/{n}` | The bytes of one chunk (`Content-Type: application/octet-stream`), in order from 0, each exactly `chunkSize` except the last. A chunk that already arrived is accepted again without change, so an interrupted upload resumes at the file's `chunks`; 409 `chunk_out_of_order` names the next one. |
| GET | `/inbox/imports/{id}` | Progress: `status` (`uploading`, `processing`, `completed`, `failed`, `canceled`), `counts` (`imported`, `skipped`, `failed`), `processedBytes` of `totalBytes`, each file's state and the first 20 `errors` (file, position, Message-ID, code, message). |
| GET | `/inbox/imports` | Recent imports into mailboxes you can read. |
| DELETE | `/inbox/imports/{id}` | Cancel: nothing more is read and the uploaded files are deleted. Messages imported so far stay. |
| POST | `/inbox/imports/preview` | An `.eml` as the body (`message/rfc822`, at most 25 MB): its headers, bodies and attachment names, without storing anything. The Mac app's viewer uses it. |

How it runs: uploaded chunks are kept in the server's file storage (the data folder on Node, R2 bound as `FILES` on Cloudflare Workers; without it the API answers 503 `import_storage_unavailable`), never whole in memory. Each file is imported in the background as soon as it is complete, while later files still upload. The `inbox_import` job reads an mbox as a stream, stores message after message and stops at its query budget (on D1 the invocation budget, as campaign jobs do) or after 20 seconds, saves its position and continues in a new job; a lease keeps two runs off the same import. Every run first checks that whoever started the import can still read the target: the person (also the member behind an API key) must still be a member who can read the mailbox or connected account, and the API key it was started with must still work. Otherwise the import is canceled (error `access_lost`); mail imported so far stays. A file's chunks are deleted once it is imported, and when an import is canceled, fails or expires, by the `inbox_import_cleanup` job: 25 chunks per run, continuing in a new job, so a large file is never left half deleted by a request limit (Workers subrequests). Maintenance looks every hour for files of finished imports whose chunks were not all deleted and deletes them again; a finished import is only forgotten once its chunks are gone. Uploads that receive nothing for a day expire; finished imports are listed for 90 days.

Limits:

| Limit | Default | Setting | When reached |
|---|---|---|---|
| Size of one import (its files together) | 10 GB | `ONESEND_INBOX_IMPORT_MAX_MB` (1 to 102,400) | 413 `import_too_large` |
| Size of one import started by a member who is not a workspace owner or admin | 1 GB | `ONESEND_INBOX_IMPORT_MEMBER_MAX_MB` (1 to 102,400) | 403 `import_needs_admin` |
| Bytes a workspace uploads for imports in 24 hours (canceled and failed imports count) | 20 GB | `ONESEND_INBOX_IMPORT_DAILY_MB` (1 to 1,048,576) | 429 `import_daily_limit` |
| Imports a workspace starts in 24 hours | 200 | | 429 `import_daily_limit` |
| Messages read from one import (imported, skipped and failed) | 200,000 | `ONESEND_INBOX_IMPORT_MAX_MESSAGES` (1 to 10,000,000) | the import fails with `too_many_messages`; mail imported so far stays |
| Unfinished imports per workspace | 5 | | 409 `too_many_imports` |
| Files per import | 1,000 | | 400 |

Large imports are limited to owners and admins so that one member cannot fill the server's storage and job queue; a member can still bring in a large mailbox as several imports of up to 1 GB, within the daily limit. You need to be able to read the mailbox (see [Who can read a mailbox](#who-can-read-a-mailbox)) or the connected account; keys limited to some mailboxes and apps (OAuth, MCP) cannot import.

## Drive

The team's files next to its mail: a My Drive for each member and shared drives with the same access rules as mailboxes (`workspace`, `members`, personal), resumable uploads, previews, versions, Trash, sharing with members and public links. Attach drive files to messages (`{ "driveFileId": … }` in `attachments`, or a link for large files) and save files of received mail to the drive: see [Drive](https://onesend.email/docs/drive/).

## Calendar and booking pages

Each member has a personal calendar, the team can share calendars, events can repeat, and invitations go out by email from your own addresses (iMIP), with answers coming back by email or from a link. Received invitations show a card with Accept, Maybe and Decline in the reader. People outside the workspace can book a free time with you on your booking page, without an account. See [Calendar](https://onesend.email/docs/calendar/) and [Booking pages](https://onesend.email/docs/booking/).

## Agents

Give an AI agent its own mailbox, a key limited to it, a live stream of new mail and replies that wait for your approval: see [Agent inbox](https://onesend.email/docs/agent-inbox/).

## Mail apps

Read and answer a mailbox from Apple Mail, Outlook, Thunderbird or a phone with IMAP, POP3 and SMTP, signing in with the address and an app password: see [Mail apps](https://onesend.email/docs/mail-clients/).

## SDK, CLI and MCP

```ts
const box = await onesend.inbox.createMailbox({ domainId, localPart: 'support' });
await onesend.inbox.rules.create({ name: 'VIP', conditions: [{ field: 'from', op: 'ends_with', value: '@bigcustomer.example' }], actions: [{ type: 'assign', userId: 'usr_…' }] });
const page = await onesend.inbox.search('label:billing is:unread');
await onesend.inbox.compose({ mailboxId: box.id, to: ['pat@partner.example'], subject: 'Hello', text: 'Hi Pat' });
```

```bash
npm run -s onesend -- mailboxes create @acme.dev --ttl 1h --label e2e
npm run -s onesend -- inbox ls --q "is:unread from:ann"
npm run -s onesend -- inbox send --from support@acme.dev --to pat@partner.example --subject Hello --text "Hi Pat"
```

Endpoints added with mailbox domains, access and Trash/Spam (migration 0041): `domains`, `access`, `accessUserIds`, `ownerUserId` on `POST/PATCH /inbox/mailboxes`, `GET /inbox/folders/{folder}/count`, `POST /inbox/folders/{folder}/empty`, and `trashRetentionDays` on `/inbox/settings`.

MCP tools: `list_mailboxes`, `create_mailbox`, `delete_mailbox`, `search_inbox`, `read_inbox_message`, `reply_inbox_message`, `compose_email`, `label_thread`, `assign_thread` and `add_note`. See [SDK and CLI](https://onesend.email/docs/sdk-and-cli/) and [MCP](https://onesend.email/docs/mcp/).
