# mta.submitOutbound

Submit outbound email message.

Submits a raw MIME message for outbound relay, local delivery, forwarding, or webhook execution with per-recipient fan-out. Who calls it: the platform's SMTP submission gateway (system key, submitting on the authenticated user's behalf); an account key may also call it directly to submit pre-built MIME as any sender address the account owns. For structured sending prefer POST /mailboxes/\{mailboxId\}/send, which builds the MIME for you; this door is for callers that already have the bytes. Lone CR and LF are normalized to CRLF before parsing or delivery; the size limit applies to the normalized message.

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

It calls `POST /deliver/outbound`: [Submit outbound email message](/docs/api/delivery/post_DeliverOutbound) in the API reference.

## Example

```ts
const deliverResult = await openemail.mta.submitOutbound(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 |
| --- | --- | --- | --- |
| `save` | `boolean` | query `save` | Save a copy to the sender's Sent folder |
| `bounce` | `boolean` | query `bounce` | Generate a bounce report (DSN) to the sender if relay fails permanently (default true) |
| `deliveryId` | `string` | header `x-delivery-id` | Caller transaction ID and idempotency key |
| `envelopeFrom` | `string` | header `x-envelope-from` | Required. Sender email address (MAIL FROM) |
| `envelopeTo` | `string` | header `x-envelope-to` | Required. Recipient email address (RCPT TO) |
| `acceptHeld` | `string` | header `x-accept-held` | `1` from the system key: smtp-in's submission 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 at once by a delivery-status notice in the sending mailbox. Ignored from any other caller and for any other refusal. |
| `sourceHost` | `string` | header `x-source-host` | MTA submission hostname |
| `deliveryMeta` | `string` | header `x-delivery-meta` | JSON delivery metadata string (max 8 KB) |

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, invalid_save / invalid_bounce, empty_body, delivery_meta_too_large / delivery_meta_not_object / delivery_meta_invalid_json, invalid_from (missing or unparseable RFC5322 From, non-system callers), header_block_too_large (the header block runs past the 64 KB parse window, so a Bcc could not be ruled out and the message cannot safely be relayed). |
| `401` | unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge |
| `403` | Permanent submission refusals, which the MTA answers with an in-session 550 and never retries: sender_not_owned (one indistinguishable reply for EVERY not-yours case — an anti-enumeration collapse, so the caller learns nothing about which addresses exist), sender_not_local, sending_disabled (ONE code across three scopes — this mailbox's own freeze, its domain's, or its account's; same code, same permanence, so an operator debugging a refusal checks all three), from_not_owned, from_sending_disabled (the RFC 5322 From is not the sender's to use), mailbox_gone (the sending mailbox was deleted mid-submission), recipient_not_permitted (one of the sender's own policies excludes this recipient: the outbound recipient allowlist — the identity's, or the credential's own — or the sender's outbound address lists, which a `block *@*` makes "send to nobody but"; the body's `source` says which, and for a list names the deciding `list` and `pattern`), recipient_not_verified (the sending account is not yet vetted, so it may send only to its verified recipients: addresses on its own domains, and outside addresses whose owners confirmed them; this recipient is neither, `source: "verified_recipients"`; vetting the account or the owner confirming lifts it. The same code when the recipient is a hosted address that forwards — a remote route, a pattern or catch-all whose destination is remote, or an alias pattern — for an account not yet vetted, to a target that is not one of THAT account's verified recipients: the forward's owner is judged, never the sender), sender_blocked (a LOCAL recipient's inbound address lists refuse this sender; permanent, and the recipient's list is not named), credential_scope (the credential in play — the bearer's, or the one X-Acting-Credential names — is scoped below `send`; permanent for that credential, carrying `scope` and `required`), receiving_disabled (a local recipient is not accepting mail: its domain, or the recipient mailbox's receive hold is `disabled`, then with `policyScope: "mailbox"`, never to be cached or gossiped), posting_denied (a members-only group refused this poster), too_many_recipients (the submission's own recipient count exceeds the sender's recipient cap — an empty window would refuse it too, so unlike the 429 rate_limited this can never clear and must bounce). **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 submit here — an operator fault, and a 550 would reject every message the server handles. account_deleted says the CALLING account is inside its deletion window, which a restore reverses (see isPermanentHold in src/db/sendhold.ts, which excludes it deliberately), so the backlog must be held rather than bounced. |
| `404` | mailbox_gone (the recipient's mailbox was deleted mid-flight) or unknown_address (the recipient is on a domain we host and receive for, and no route matches). Both are permanent — 550 5.1.1. A 404 carrying NO error code is something else entirely: this route was never reached and the delivery URL is missing its /api/v1/deliver/outbound path, so it must DEFER, exactly as core's own relay defers on 404/405/415 rather than bouncing on an operator typo (MTA_MISCONFIG_STATUSES in src/queues/relay.ts). |
| `409` | delivery_id_reused — this delivery ID belongs to a composed or scheduled submission, or its original retry window has expired. Use a fresh ID for a new submission. |
| `411` | length_required — Content-Length header is required |
| `413` | too_large — message exceeds maximum allowed size |
| `429` | TEMPORARY — retry, never bounce; every code carries `Retry-After`. rate_limited (the sender is over a send allowance), sending_paused (a reversible hold on the sender — non-payment, an investigation — at any of the three scopes), from_sending_paused (the same hold, found via the RFC5322 From address's domain), receiving_paused (a LOCAL recipient's account is inside its deletion window, or the recipient mailbox's receive hold is `paused`, then with `policyScope: "mailbox"`; the message must be retried so a restore, or a cleared hold, receives what arrived meanwhile). |
| `500` | internal_error |
| `503` | Temporary — retry with the same delivery ID: temporary_failure (staging or infrastructure fault, a local recipient's receive policy could not be established, or a recipient's forward could not establish its verified-recipient policy or verdict, including an old unrestricted flag from an outage fallback), superseded / reaped (this attempt lost its pending intent; a keyed retry converges), staging_missing (the staged upload vanished before the recipient leg ran; a retry re-stages), submission_record_unavailable (the delivery ID's durable admission could not be read, reserved, or validated). |
| `507` | Temporary — out of room, so the MTA queues. THREE codes, and the difference is the remedy: over_quota is the recipient mailbox's own quota, account_over_quota is the recipient tenant's shared storage pool (a mailbox well under its own quota can still be refused) — both are numbers an operator can raise — while store_metadata_full is the recipient 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).
