# mta.deliverInbound

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.

```ts
openemail.mta.deliverInbound(
  message: RawBody,
  options: MtaDeliverInboundOptions,
): ApiPromise<DeliverResult>
```

It calls `POST /deliver/inbound`: [Deliver inbound email message](/docs/api/delivery/post_DeliverInbound) in the API reference.

## Example

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

## Arguments

| Argument | Type | Description |
| --- | --- | --- |
| `message` | [`RawBody`](/docs/sdks/typescript/calling-methods#raw-bodies) | Raw RFC 5322 MIME message bytes. The request's body, as bytes: text, a `Blob`, an `ArrayBuffer` or a `Uint8Array` ([raw bodies](/docs/sdks/typescript/calling-methods#raw-bodies)). |

## Options

The last argument, `options`, takes:

| Option | Type | Sent as | Description |
| --- | --- | --- | --- |
| `deliveryId` | `string` | header `x-delivery-id` | Caller transaction ID and idempotency key |
| `envelopeFrom` | `string` | header `x-envelope-from` | Required. SMTP envelope sender (MAIL FROM) |
| `envelopeTo` | `string` | header `x-envelope-to` | Required. SMTP envelope recipient (RCPT TO) |
| `sourceHost` | `string` | header `x-source-host` | MTA receiving hostname |
| `deliveryMeta` | `string` | header `x-delivery-meta` | JSON delivery metadata string (max 8 KB) |
| `acceptHeld` | `string` | header `x-accept-held` | `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. |

Every call also takes `signal`, `timeout`, `retry` and `headers`, which say how that one call is sent ([call options](/docs/sdks/typescript/calling-methods#call-options)).

## Answer

Awaited, it is the API's JSON, [`DeliverResult`](/docs/sdks/typescript/types/deliver-result). It is an [`ApiPromise`](/docs/sdks/typescript/responses): `.withResponse()` gives the same with the `Response` it came in, for its headers.

## Retries

When a call gives no `deliveryId` (the `x-delivery-id` header), the client makes one, the same for each of the call's retries, so it is retried like a read: the API converges on one send. Give your own to make your own retries safe too ([retries and idempotent sends](/docs/sdks/typescript/errors#retries-and-idempotent-sends)).

## Errors

| Status | What it means |
| --- | --- |
| `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. |
| `401` | unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge |
| `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. |
| `404` | unknown_address or mailbox_gone |
| `411` | length_required — Content-Length header is required |
| `413` | too_large — message exceeds maximum allowed size |
| `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. |
| `500` | internal_error |
| `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. |
| `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. |

A failed call rejects with a [`RequestError`](/docs/sdks/typescript/errors): its `status`, and its `code`, the API's `error`. Decide on the code: one status covers several.

## Types

It names these types of the API, each on a page of its own: [`DeliverResult`](/docs/sdks/typescript/types/deliver-result).
