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.
openemail.mta.submitOutbound(
message: RawBody,
options: MtaSubmitOutboundOptions,
): ApiPromise<DeliverResult>It calls POST /deliver/outbound: Submit outbound email message in the API reference.
Example
const deliverResult = await openemail.mta.submitOutbound(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 |
|---|---|---|---|
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).
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, 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: 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.