messages.compose
Save structured message to mailbox.
Constructs and saves an email message from structured JSON (headers, body text/HTML, attachments) into a mailbox without sending.
openemail.messages.compose(
mailboxId: string,
body: MessagesComposeBody,
options?: MessagesComposeOptions,
): ApiPromise<AppendResult>It calls POST /mailboxes/{mailboxId}/messages/compose: Save structured message to mailbox in the API reference.
Example
const appendResult = await openemail.messages.compose(mailboxId, {
from: { email: 'grace@acme.example', name: 'Grace Hopper' },
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 | MessagesComposeBody | The request's body. |
Options
The last argument, options, a MessagesComposeOptions, takes:
| Option | Type | Sent as | Description |
|---|---|---|---|
label | string | query label | Target label (default INBOX) |
flags | string | query flags | Comma-separated initial flags, e.g. seen,draft |
filter | boolean | query filter | Whether to run the mailbox's active Sieve filter (default false) |
internaldate | number | query internaldate | Epoch seconds recorded as receivedAt (default now) |
deliveryId | string | header x-delivery-id | Optional client idempotency key to prevent duplicate imports. Stored NAMESPACED as append:<your id> (an append is the mailbox's own side writing its own row, announced as message.imported, not message.new), so the traffic log and the filtered response show that form — retry with your original value. |
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, AppendResult. 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, invalid_flag, invalid delivery id, or a message the server refused to build (header_newline, reserved_header, invalid_address, invalid_base64, …) — the field names the offending input |
401 | unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a WWW-Authenticate: Bearer challenge |
403 | receiving_disabled (policyScope "mailbox"): this mailbox's receive hold is disabled, and the caller reaches it through a share grant. A grantee's write is refused as arriving mail is; the mailbox's own user and its account write as ever. |
404 | Mailbox not found/not accessible, unknown_label, or mailbox_gone |
411 | Content-Length required |
413 | JSON body exceeds MAX_JSON_BODY_BYTES, or the assembled message exceeds MAX_MESSAGE_BYTES |
429 | receiving_paused (policyScope "mailbox", with Retry-After): this mailbox's receive hold is paused, and the caller reaches it through a share grant. Retry once the owner clears it. |
503 | superseded/reaped (lost pending intent; retry with the same X-Delivery-Id), or temporary_failure (this mailbox's receive policy could not be established for a grantee's write; retry) |
507 | over_quota (mailbox storage limit), account_over_quota (the account storage pool), or store_metadata_full (the store's own metadata ceiling — no limit to raise; purging messages is the remedy) — distinct so the client knows which remedy applies |
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
MessagesComposeBody
/** The body of `messages.compose`. */
type MessagesComposeBody = {
attachments?: MessagesComposeBodyAttachmentsItem[]
bcc?: MailAddress[]
cc?: MailAddress[]
from: MailAddress
/** Extra headers; structural ones (Content-Type, Date, …) are refused */
headers?: Record<string, string>
/** HTML body; paired with text as multipart/alternative */
html?: string | null
/** Parent Message-ID, angle-bracketed */
inReplyTo?: string | null
/** Overrides the generated Message-ID */
messageId?: string | null
references?: string[]
replyTo?: MailAddress[]
subject?: string | null
/** Plain-text body */
text?: string | null
to?: MailAddress[]
}MessagesComposeBodyAttachmentsItem
/** The API's `MessagesComposeBodyAttachmentsItem`, as the document describes it. */
type MessagesComposeBodyAttachmentsItem = {
/** 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: AppendResult, MailAddress.