# messages.send

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.

```ts
openemail.messages.send(
  mailboxId: string,
  body: MessagesSendBody,
  options?: MessagesSendOptions,
): ApiPromise<MessagesSendResult>
```

It calls `POST /mailboxes/{mailboxId}/send`: [Send an email message](/docs/api/delivery/post_MessageSend) in the API reference.

## Example

```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' }],
})
```

## Arguments

| Argument | Type | Description |
| --- | --- | --- |
| `mailboxId` | `string` | Mailbox ULID identifier. The path's `{mailboxId}`. |
| `body` | [`MessagesSendBody`](#messagessendbody) | The request's body. |

## Options

The last argument, `options`, a `MessagesSendOptions`, takes:

| Option | Type | Sent as | Description |
| --- | --- | --- | --- |
| `save` | `boolean` | query `save` | Save a copy to Sent folder (default true) |
| `bounce` | `boolean` | query `bounce` | Deliver a bounce notice (DSN) to this mailbox if relay fails (default true) |
| `deliveryId` | `string` | header `x-delivery-id` | 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. |

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, [`MessagesSendResult`](#messagessendresult). 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` | 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) |
| `401` | unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge |
| `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) |
| `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). |
| `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. |
| `411` | Content-Length required |
| `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) |
| `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`. |
| `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. |
| `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) |
| `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) |

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

### MessagesSendBody

```ts
/** The body of `messages.send`. */
type MessagesSendBody = {
  /** List of file attachments */
  attachments?: MessagesSendBodyAttachmentsItem[]
  /** 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) */
  autoSubmitted?: ('auto-generated' | 'auto-replied') | null
  /** Blind carbon copy recipient email addresses (hidden from message headers) */
  bcc?: MailAddress[]
  /** Carbon copy recipient email addresses */
  cc?: MailAddress[]
  /** Sender email address (must belong to this mailbox) */
  from: MailAddress
  /** Additional custom email headers */
  headers?: Record<string, string>
  /** HTML body */
  html?: string | null
  /** In-Reply-To Message-ID */
  inReplyTo?: string | null
  /** References header Message-IDs */
  references?: string[]
  /** Reply-To email addresses */
  replyTo?: MailAddress[]
  /** 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). */
  sendAt?: number | null
  /** Message subject line */
  subject?: string | null
  /** Plain text body */
  text?: string | null
  /** Primary recipient email addresses */
  to?: MailAddress[]
}
```

### MessagesSendResult

```ts
/** What `messages.send` answers. */
type MessagesSendResult = SendResult | ScheduledSend
```

### MessagesSendBodyAttachmentsItem

```ts
/** The API's `MessagesSendBodyAttachmentsItem`, as the document describes it. */
type MessagesSendBodyAttachmentsItem = {
  /** Staged-upload form: a blobId from POST /mailboxes/{id}/uploads (or JMAP /upload) */
  blobId?: string
  /** Inline form: base64 payload */
  content?: string
  contentId?: string | null
  /** Defaults to the stored part's / upload's type for a reference or blob, else application/octet-stream */
  contentType?: string | null
  /** Required for an inline attachment. For a reference or a staged upload, defaults to the stored part's filename (or "attachment"). */
  filename?: string
  /** Reference form: a message in THIS mailbox to take the part from */
  messageId?: string
  /** Reference form: the part's section, as reported by /messages/{id}/content */
  section?: string
}
```

It names these types of the API, each on a page of its own: [`MailAddress`](/docs/sdks/typescript/types/mail-address), [`ScheduledSend`](/docs/sdks/typescript/types/scheduled-send), [`SendResult`](/docs/sdks/typescript/types/send-result).
