# 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.

## `POST /api/v1/deliver/outbound`

### Query parameters

- `save` ("true" | "false") — Save a copy to the sender's Sent folder
- `bounce` ("true" | "false") — Generate a bounce report (DSN) to the sender if relay fails permanently (default true)

### Header parameters

- `x-delivery-id` (string, required, min 1 chars) — Caller transaction ID and idempotency key
- `x-envelope-from` (string, required) — Sender email address (MAIL FROM)
- `x-envelope-to` (string, required) — Recipient email address (RCPT TO)
- `x-accept-held` (string) — `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.
- `x-source-host` (string) — MTA submission hostname
- `x-delivery-meta` (string) — JSON delivery metadata string (max 8 KB)
- `content-length` (string, required) — MIME message size in bytes

### Request body (required)

`message/rfc822`

Type: string

### Responses

**200** — Message delivered to local recipient mailbox

`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 outbound relay or forwarding, or (with X-Accept-Held from the system key) for a local 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, 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).

`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 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.

`application/json` → ErrorBody

**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).

`application/json` → ErrorBody

**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.

`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, 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).

`application/json` → ErrorBody

**500** — internal_error

`application/json` → ErrorBody

**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).

`application/json` → ErrorBody

**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.

`application/json` → ErrorBody

### Example request

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

## TypeScript SDK

[`openemail.mta.submitOutbound`](/docs/sdks/typescript/mta/submit-outbound)

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