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.
openemail.mta.deliverInbound(
message: RawBody,
options: MtaDeliverInboundOptions,
): ApiPromise<DeliverResult>It calls POST /deliver/inbound: Deliver inbound email message in the API reference.
Example
const deliverResult = await openemail.mta.deliverInbound(message, {
envelopeFrom: 'ada@example.com',
envelopeTo: 'ada@example.com',
})Arguments
| Argument | Type | Description |
|---|---|---|
message | RawBody | Raw RFC 5322 MIME message bytes. The request's body, as bytes: text, a Blob, an ArrayBuffer or a Uint8Array (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).
Answer
Awaited, it is the API's JSON, DeliverResult. It is an ApiPromise: .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).
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: 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.