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.
openemail.messages.send(
mailboxId: string,
body: MessagesSendBody,
options?: MessagesSendOptions,
): ApiPromise<MessagesSendResult>It calls POST /mailboxes/{mailboxId}/send: Send an email message in the API reference.
Example
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 | 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).
Answer
Awaited, it is the API's JSON, MessagesSendResult. 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 | 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: its status, and its code, the API's error. Decide on the code: one status covers several.
Types
MessagesSendBody
/** 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
/** What `messages.send` answers. */
type MessagesSendResult = SendResult | ScheduledSendMessagesSendBodyAttachmentsItem
/** 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, ScheduledSend, SendResult.