# Deliver inbound email message

Processes and delivers an inbound MIME email message to a mailbox, webhook, forwarding address, or mailing group with Sieve filter execution. Who calls it: the platform's inbound MTA at DATA time (system key, any recipient); an account key may also call it to inject mail, confined to recipients on domains the account owns. Mailbox app passwords are refused (403 insufficient_scope). Most integrations never call this: mail arrives by being sent to your address.

## `POST /api/v1/deliver/inbound`

### Header parameters

- `x-delivery-id` (string, required, min 1 chars) — Caller transaction ID and idempotency key
- `x-envelope-from` (string, required) — SMTP envelope sender (MAIL FROM)
- `x-envelope-to` (string, required) — SMTP envelope recipient (RCPT TO)
- `x-source-host` (string) — MTA receiving hostname
- `x-delivery-meta` (string) — JSON delivery metadata string (max 8 KB)
- `x-accept-held` (string) — `1` from the system key: smtp-in's re-post of a recipient it set aside because the recipient mailbox's receive hold refused it (`policyScope: "mailbox"`) after another recipient of the same transaction committed. The leg is accepted and staged (202) instead of refused: a paused one is delivered once the hold clears, or reported to the sender as expired at the paced queue's deadline; a disabled one is reported to the sender at once (a delivery-status notice; none to a null reverse-path, whose leg is kept for the operator). Ignored from any other caller and for any other refusal.
- `content-length` (string, required) — MIME message size in bytes

### Request body (required)

`message/rfc822`

Type: string

### Responses

**200** — Message delivered to mailbox or processed by Sieve filter

`application/json` → DeliverResult

- _option 1: object_
  - `duplicate` (boolean, required) — True if message was an idempotent duplicate
  - `messageId` (string, required) — Assigned message ULID
  - `status` ("delivered", required) — Message was immediately delivered to mailbox
  - `threadId` (string | null, required) — Conversation thread ULID, or null
  - `uid` (integer | null, required) — IMAP UID in inbox, or null
  - `uidValidity` (integer | null, required) — IMAP UIDVALIDITY epoch, or null
  - `sentCopy` ("saved" | "duplicate" | "over_quota") — Status of saved sent copy
  - `sentThreadId` (string | null) — Thread ID of saved sent copy
- _option 2: object_
  - `deliveryId` (string, required) — Delivery identifier
  - `status` ("filtered", required) — Message was silently discarded or filed by Sieve rule
  - `sentCopy` ("saved" | "duplicate" | "over_quota") — Status of saved sent copy
  - `sentThreadId` (string | null) — Thread ID of saved sent copy
- _option 3: object_
  - `deliveryId` (string, required) — Delivery identifier
  - `status` ("queued", required) — Message was queued for background relay or delivery
  - `sentCopy` ("saved" | "duplicate" | "over_quota") — Status of saved sent copy
  - `sentThreadId` (string | null) — Thread ID of saved sent copy

**202** — Message staged and queued for webhook or forwarding, a paced mailbox, or (with X-Accept-Held from the system key) a mailbox whose receive hold refused it

`application/json` → DeliverResult

- _option 1: object_
  - `duplicate` (boolean, required) — True if message was an idempotent duplicate
  - `messageId` (string, required) — Assigned message ULID
  - `status` ("delivered", required) — Message was immediately delivered to mailbox
  - `threadId` (string | null, required) — Conversation thread ULID, or null
  - `uid` (integer | null, required) — IMAP UID in inbox, or null
  - `uidValidity` (integer | null, required) — IMAP UIDVALIDITY epoch, or null
  - `sentCopy` ("saved" | "duplicate" | "over_quota") — Status of saved sent copy
  - `sentThreadId` (string | null) — Thread ID of saved sent copy
- _option 2: object_
  - `deliveryId` (string, required) — Delivery identifier
  - `status` ("filtered", required) — Message was silently discarded or filed by Sieve rule
  - `sentCopy` ("saved" | "duplicate" | "over_quota") — Status of saved sent copy
  - `sentThreadId` (string | null) — Thread ID of saved sent copy
- _option 3: object_
  - `deliveryId` (string, required) — Delivery identifier
  - `status` ("queued", required) — Message was queued for background relay or delivery
  - `sentCopy` ("saved" | "duplicate" | "over_quota") — Status of saved sent copy
  - `sentThreadId` (string | null) — Thread ID of saved sent copy

**400** — Permanent — the request is malformed and a retry cannot help: validation_failed, missing_delivery_id, invalid_envelope, empty_body, delivery_meta_too_large / delivery_meta_not_object / delivery_meta_invalid_json.

`application/json` → ErrorOrValidation

**401** — unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge

`application/json` → ErrorBody

**403** — Permanent per-message refusals, which the MTA answers with an in-session 550: receiving_disabled (the recipient's domain is not accepting mail, or the destination mailbox's receive hold is `disabled`: then the body carries `policyScope: "mailbox"`, never to be cached or gossiped), sender_blocked (an inbound address list refused this sender), posting_denied (a members-only group refused a poster who is not an authenticated member), recipient_not_verified (the address forwards — a remote route, a pattern or catch-all whose destination is remote, or an alias pattern — for an account that is not yet vetted, to a target that is not one of its verified recipients: an address on its own domains, or one whose owner confirmed it, another customer's address included; nothing is stored or relayed, and vetting the account or the owner confirming lifts it; GET /deliver/check refuses the same recipient with the same code at RCPT). **Key on the CODE, never on 403 alone**: two classes of 403 are NOT permanent and must DEFER (451). insufficient_scope / system_credentials_required say the caller's own bearer may not deliver here — a deployment fault rather than a fact about the message, and a 550 would hard-bounce every message the server sees. account_deleted says the CALLING account is inside its deletion window, which a restore reverses. Note sender_blocked depends on the ENVELOPE SENDER as well as the recipient, so it must never be cached under a recipient key alone.

`application/json` → ErrorBody

**404** — unknown_address or mailbox_gone

`application/json` → ErrorBody

**411** — length_required — Content-Length header is required

`application/json` → ErrorBody

**413** — too_large — message exceeds maximum allowed size

`application/json` → ErrorBody

**429** — Temporary, retry after the specified delay: receiving_paused (the recipient account is inside its deletion window, or the destination mailbox's receive hold is `paused`, then with `policyScope: "mailbox"`; a restore or a cleared hold receives the backlog) or rate_limited (the domain's forwarding budget is exhausted: the wire code is rate_limited; forward_rate_limited is the traffic log's detail, never the response body's error). rate_limited also answers a recipient whose tenant is over its delivery admission share, or whose admission check could not answer just now; the traffic log's detail is then admission_shed or admission_unavailable respectively. recently_unknown: the recipient did not resolve moments ago and is not asked again until that answer is a minute old (the object directory's negative memo); it may have been created since, so this DEFERS and never bounces, and Retry-After is at most the seconds left before it is asked again. Only the first miss answers 404 unknown_address.

`application/json` → ErrorBody

**500** — internal_error

`application/json` → ErrorBody

**503** — temporary_failure — retry with the same delivery ID. Also the answer when the destination mailbox's receive policy could not be established (its store could not confirm whether a receive hold is set): nothing was stored, and the retry decides. And when a forward's verified-recipient policy or verdict could not be established, including an outage fallback whose old flag cannot settle an unverified target: before staging for a route, so nothing was stored; after storing for a forward TAP's copy, whose retry is answered as a duplicate and owes the copy again.

`application/json` → ErrorBody

**507** — Temporary — out of room, so the MTA queues. THREE codes, and the difference is the remedy: over_quota is THIS mailbox's own quota, account_over_quota is the tenant's shared storage pool (a mailbox well under its quota can still be refused) — both are numbers an operator can raise — while store_metadata_full is the store's own metadata ceiling, which no number clears: only purging messages does. A client that cannot tell them apart tells the customer the wrong remedy.

`application/json` → ErrorBody

### Example request

```bash
curl -X POST 'https://api.open.email/api/v1/deliver/inbound' \
  -H 'Authorization: Bearer oek_…' \
  -H 'Content-Type: message/rfc822'
```

## TypeScript SDK

[`openemail.mta.deliverInbound`](/docs/sdks/typescript/mta/deliver-inbound)

```ts
const deliverResult = await openemail.mta.deliverInbound(message, {
  envelopeFrom: 'ada@example.com',
  envelopeTo: 'ada@example.com',
})
```
