Skip to Content

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

ArgumentTypeDescription
mailboxIdstringMailbox ULID identifier. The path's {mailboxId}.
bodyMessagesComposeBodyThe request's body.

Options

The last argument, options, a MessagesComposeOptions, takes:

OptionTypeSent asDescription
labelstringquery labelTarget label (default INBOX)
flagsstringquery flagsComma-separated initial flags, e.g. seen,draft
filterbooleanquery filterWhether to run the mailbox's active Sieve filter (default false)
internaldatenumberquery internaldateEpoch seconds recorded as receivedAt (default now)
deliveryIdstringheader x-delivery-idOptional 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

StatusWhat it means
400validation_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
401unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a WWW-Authenticate: Bearer challenge
403receiving_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.
404Mailbox not found/not accessible, unknown_label, or mailbox_gone
411Content-Length required
413JSON body exceeds MAX_JSON_BODY_BYTES, or the assembled message exceeds MAX_MESSAGE_BYTES
429receiving_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.
503superseded/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)
507over_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.