# Send an email message

Sends an email from this mailbox to one or more recipients. The server builds the RFC 5322 MIME message, signs DKIM, applies outbound address list policies, and returns delivery results per recipient. Supports immediate and scheduled sending.

## `POST /api/v1/mailboxes/{mailboxId}/send`

### Path parameters

- `mailboxId` (string, required) — Mailbox ULID identifier

### Query parameters

- `save` ("true" | "false") — Save a copy to Sent folder (default true)
- `bounce` ("true" | "false") — Deliver a bounce notice (DSN) to this mailbox if relay fails (default true)

### Header parameters

- `x-delivery-id` (string) — Optional idempotency key to prevent duplicate sends on network retries. A retry with the same id converges on the original submission instead of sending again, and is not charged against the send allowance a second time. It does not get around a sending hold: while the sender is paused or disabled the retry is refused like any submission (429 sending_paused, 403 sending_disabled), and once the hold lifts it continues at its original charge.

### Request body (required)

`application/json`

- `from` (MailAddress & object, required)
  - `email` (string, required, 3–320 chars) — Email address (e.g. alice@example.com)
  - `name` (string | null, max 320 chars) — Display name (e.g. Alice Smith)
- `attachments` (object[], max 50 items) — List of file attachments
  - `blobId` (string, 1–64 chars) — Staged-upload form: a blobId from POST /mailboxes/{id}/uploads (or JMAP /upload)
  - `content` (string) — Inline form: base64 payload
  - `contentId` (string | null, max 255 chars)
  - `contentType` (string | null, max 255 chars) — Defaults to the stored part's / upload's type for a reference or blob, else application/octet-stream
  - `filename` (string, 1–255 chars) — Required for an inline attachment. For a reference or a staged upload, defaults to the stored part's filename (or "attachment").
  - `messageId` (string, 1–64 chars) — Reference form: a message in THIS mailbox to take the part from
  - `section` (string, max 64 chars, pattern `^[0-9]+(\.[0-9]+)*$`) — Reference form: the part's section, as reported by /messages/{id}/content
- `autoSubmitted` ("auto-generated" | "auto-replied") — RFC 3834 marker for mail an automaton sends: auto-generated (a notification) or auto-replied (an answer to a message). Written as the Auto-Submitted header so a receiver's loop guards recognise it; refused alongside a free-form Auto-Submitted in headers (auto_submitted_conflict)
- `bcc` (MailAddress[], max 50 items) — Blind carbon copy recipient email addresses (hidden from message headers)
  - `email` (string, required, 3–320 chars) — Email address (e.g. alice@example.com)
  - `name` (string | null, max 320 chars) — Display name (e.g. Alice Smith)
- `cc` (MailAddress[], max 50 items) — Carbon copy recipient email addresses
  - `email` (string, required, 3–320 chars) — Email address (e.g. alice@example.com)
  - `name` (string | null, max 320 chars) — Display name (e.g. Alice Smith)
- `headers` (object) — Additional custom email headers
- `html` (string | null) — HTML body
- `inReplyTo` (string | null, max 512 chars) — In-Reply-To Message-ID
- `references` (string[], max 50 items) — References header Message-IDs
- `replyTo` (MailAddress[], max 10 items) — Reply-To email addresses
  - `email` (string, required, 3–320 chars) — Email address (e.g. alice@example.com)
  - `name` (string | null, max 320 chars) — Display name (e.g. Alice Smith)
- `sendAt` (integer | null) — Release time, epoch seconds. In the future ⇒ the message is stored as a draft and sent then (202 + a schedule); at or before now ⇒ sent immediately. Requires the Sent copy (`?save` may not be false).
- `subject` (string | null, max 2000 chars) — Message subject line
- `text` (string | null) — Plain text body
- `to` (MailAddress[], max 50 items) — Primary recipient email addresses
  - `email` (string, required, 3–320 chars) — Email address (e.g. alice@example.com)
  - `name` (string | null, max 320 chars) — Display name (e.g. Alice Smith)

### Responses

**200** — Every recipient was accepted (delivered, queued, or filtered)

`application/json` → SendResult

- `deliveryId` (string, required) — Master submission delivery ID
- `recipients` (SendRecipientResult[], required) — Outcome status per recipient
  - `address` (string, required) — Recipient email address
  - `deliveryId` (string, required) — Unique delivery attempt ID for this recipient
  - `status` ("delivered" | "queued" | "filtered" | "failed", required) — Outcome status for this recipient
  - `error` (string) — Error reason code if status is failed (e.g. 'over_quota', 'receiving_disabled'). 'sending_paused' and 'sending_disabled' mean a hold on the sender (mailbox, domain or account) landed while the request was running: recipients already handled keep their status and the rest are refused. 'sending_paused' is temporary: retry with the same X-Delivery-Id once the hold lifts. 'sending_disabled' is permanent. 'recipient_not_verified' is permanent for this recipient alone: the account is not yet vetted, so it may send only to its verified recipients (its own domains, and outside addresses whose owners confirmed them), and this one is neither; or the recipient is a hosted address that forwards for an account not yet vetted, to a target that is not one of that account's verified recipients.
  - `list` (string) — On an address-list refusal: the sender's list that decided
  - `pattern` (string) — On an address-list refusal: the entry that decided (`*@*` for a block-all)
  - `source` ("permitted_recipients" | "address_list" | "verified_recipients") — On 'recipient_not_permitted': which of the sender's own policies refused it, the identity or credential allowlist, or the sender's outbound address lists. On 'recipient_not_verified': 'verified_recipients', the verified-recipients rule of the sending account, or of the account the recipient forwards for
- `sentCopy` ("saved" | "duplicate" | "over_quota") — Status of saving copy to Sent folder ('saved', 'duplicate', 'over_quota')
- `sentThreadId` (string | null) — Conversation thread ID of the saved sent message

**202** — Scheduled (`sendAt` in the future): the message is stored as a draft and released at that time. The delivery id is SPENT by the schedule — a later submission carrying the same `X-Delivery-Id` answers this same resource rather than sending again, whatever state it has reached (`state` says which), so a retry can never un-cancel or double-send

`application/json` → ScheduledSend

- `attempts` (integer, required) — Number of delivery attempts made
- `createdAt` (integer <int64>, required) — Creation timestamp in epoch seconds
- `deferrals` (integer, required) — Number of deferrals encountered
- `deliveryId` (string, required) — Idempotency key for this submission
- `error` (string | null, required) — Error reason if sending failed or was canceled, or null
- `finishedAt` (integer | null, required) — Completion timestamp in epoch seconds, or null if pending
- `messageId` (string, required) — Draft message ULID scheduled for sending
- `recipients` (string[], required) — List of target recipient email addresses
- `releaseAt` (integer <int64>, required) — Actual scheduled release time in epoch seconds
- `result` (array | null, required) — Per-recipient delivery outcomes, or null if pending
- `scheduleId` (string, required) — Scheduled send ULID
- `sendAt` (integer <int64>, required) — Requested send time in epoch seconds
- `state` ("pending" | "releasing" | "sent" | "failed" | "canceled", required) — Current scheduling status
- `threadId` (string | null, required) — Associated conversation thread ID, or null

**207** — Mixed: at least one recipient failed. The array carries each address's own status and error; retry with the same X-Delivery-Id to converge only the failures. A hold placed on the sender while the request runs refuses the recipients not yet handled with sending_paused (temporary) or sending_disabled (permanent); recipients already delivered or queued keep their status

`application/json` → SendResult

- `deliveryId` (string, required) — Master submission delivery ID
- `recipients` (SendRecipientResult[], required) — Outcome status per recipient
  - `address` (string, required) — Recipient email address
  - `deliveryId` (string, required) — Unique delivery attempt ID for this recipient
  - `status` ("delivered" | "queued" | "filtered" | "failed", required) — Outcome status for this recipient
  - `error` (string) — Error reason code if status is failed (e.g. 'over_quota', 'receiving_disabled'). 'sending_paused' and 'sending_disabled' mean a hold on the sender (mailbox, domain or account) landed while the request was running: recipients already handled keep their status and the rest are refused. 'sending_paused' is temporary: retry with the same X-Delivery-Id once the hold lifts. 'sending_disabled' is permanent. 'recipient_not_verified' is permanent for this recipient alone: the account is not yet vetted, so it may send only to its verified recipients (its own domains, and outside addresses whose owners confirmed them), and this one is neither; or the recipient is a hosted address that forwards for an account not yet vetted, to a target that is not one of that account's verified recipients.
  - `list` (string) — On an address-list refusal: the sender's list that decided
  - `pattern` (string) — On an address-list refusal: the entry that decided (`*@*` for a block-all)
  - `source` ("permitted_recipients" | "address_list" | "verified_recipients") — On 'recipient_not_permitted': which of the sender's own policies refused it, the identity or credential allowlist, or the sender's outbound address lists. On 'recipient_not_verified': 'verified_recipients', the verified-recipients rule of the sending account, or of the account the recipient forwards for
- `sentCopy` ("saved" | "duplicate" | "over_quota") — Status of saving copy to Sent folder ('saved', 'duplicate', 'over_quota')
- `sentThreadId` (string | null) — Conversation thread ID of the saved sent message

**400** — validation_failed, no_recipients, too_many_recipients, auto_submitted_conflict (autoSubmitted alongside a free-form Auto-Submitted header), a refused build (header_newline, reserved_header, invalid_address, invalid_base64, …), a bad attachment reference (unknown_message / unknown_part / part_unresolvable, each carrying the offending `index`), or a refused schedule: send_at_too_far, send_at_requires_save, recipient_not_permitted, recipient_not_verified (the account is not yet vetted and may send only to its verified recipients; carries the first `address` that is not one)

`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 — sender_not_owned | sender_not_local | sending_disabled (the mailbox, its domain, or its account may not send) | credential_scope (the credential is scoped below `send`, design D50; carries `scope` and `required`) | mailbox_gone (the sending mailbox was torn down mid-submission) | 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; distinct from the 400 of the same name, which is the per-request recipient-list bound)

`application/json` → ErrorBody

**404** — Permanent — not_found (the mailbox does not exist, or is not this caller's: cross-tenant and missing collapse to one indistinguishable answer) or mailbox_gone (the sending mailbox was torn down mid-submission).

`application/json` → ErrorBody

**409** — Permanent — delivery_id_reused: this X-Delivery-Id belongs to an accepted message with a different sender or additional recipients, an incompatible scheduled submission, or an immediate send outside its 14-day retry window. Use a fresh id for a new message. Same-key retries of the original recipient set or a subset use the original MIME, acceptance time and save/bounce choices, including when no Sent copy was saved. Expunging Sent does not release a retained immediate admission key.

`application/json` → ErrorBody

**411** — Content-Length required

`application/json` → ErrorBody

**413** — JSON body exceeds MAX_JSON_BODY_BYTES, the assembled message exceeds MAX_MESSAGE_BYTES, or attachments_too_large (referenced + inline attachment bytes exceed the per-message budget)

`application/json` → ErrorBody

**429** — TEMPORARY, and the only 4xx here that is — retry, never surface it as a permanent failure. rate_limited (the sender is over its daily msgs/rcpts allowance) and sending_paused (a reversible hold: non-payment, an investigation, or the account's deletion window) both carry `Retry-After` plus `retryAfterSeconds`; too_many_scheduled means the mailbox is at its cap of pending scheduled sends and carries `limit`.

`application/json` → ErrorBody

**500** — internal — a required Sent or Drafts label is missing; blob_unavailable — an attachment source disappeared, changed length or failed while streaming, before submission admission. Retry when the source is available.

`application/json` → ErrorBody

**503** — Sent copy lost its pending intent (superseded or reaped), or submission_record_unavailable: canonical message bytes, the original Sent reference, durable admission or submission plan could not be recovered or prepared before recipient dispatch. Retry with the same X-Delivery-Id; a permanently missing canonical source requires a new submission with a fresh id. Or temporary_failure: the platform's storage could not answer just now; retry after the Retry-After window. Any operation can answer this. A write that got it may have been applied, so retry it with the same idempotency key where it takes one, or read the state back first (see Transient failures in the API description)

`application/json` → ErrorBody

**507** — over_quota, account_over_quota, or store_metadata_full (the store's metadata ceiling; the remedy is purging messages) — a SCHEDULED send only: the draft it must store has nowhere to live. An immediate send is never refused for storage; a Sent copy that cannot be stored degrades to `sentCopy: "over_quota"` in the result instead (one collapsed word for every storage refusal)

`application/json` → ErrorBody

### Example request

```bash
curl -X POST 'https://api.open.email/api/v1/mailboxes/{mailboxId}/send' \
  -H 'Authorization: Bearer oek_…' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": {
      "email": "string"
    }
  }'
```

## TypeScript SDK

[`openemail.messages.send`](/docs/sdks/typescript/messages/send)

```ts
const result = await openemail.messages.send(mailboxId, {
  attachments: [
    {
      blobId: '01J9B0B4D7F1H3K6M000000000',
      contentType: 'application/pdf',
      filename: 'q3-report-final.pdf',
    },
  ],
  from: { email: 'grace@acme.example', name: 'Grace Hopper' },
  html: '<p>Thanks Ada, final version attached.</p><p>Grace</p>',
  inReplyTo: '<7f2a1c9e4b8d@mail.example.com>',
  references: ['<7f2a1c9e4b8d@mail.example.com>'],
  subject: 'Re: Q3 report draft',
  text: 'Thanks Ada, final version attached.\n\nGrace',
  to: [{ email: 'ada@example.com', name: 'Ada Lovelace' }],
})
```
