Skip to Content

Append raw MIME message to mailbox.

Stores raw RFC 5322 email bytes directly into a mailbox under a label without sending (similar to IMAP APPEND). Supports custom flags, Sieve filtering, and historical internaldate. Lone CR and LF are normalized to CRLF before storage; the size limit applies to the normalized message.

openemail.messages.append(
  mailboxId: string,
  message: RawBody,
  options?: MessagesAppendOptions,
): ApiPromise<AppendResult>

It calls POST /mailboxes/{mailboxId}/messages: Append raw MIME message to mailbox in the API reference.

Example

const appendResult = await openemail.messages.append(mailboxId, message)

Arguments

ArgumentTypeDescription
mailboxIdstringMailbox ULID identifier. The path's {mailboxId}.
messageRawBodyRaw RFC 5322 message bytes. The request's body, as bytes: text, a Blob, an ArrayBuffer or a Uint8Array (raw bodies).

Options

The last argument, options, a MessagesAppendOptions, takes:

OptionTypeSent asDescription
labelstringquery labelTarget label or folder (default INBOX)
flagsstringquery flagsComma-separated initial flags, e.g. seen,draft
keywordsstringquery keywordsComma-separated initial keywords (e.g. $forwarded,$mdnsent), committed WITH the store flip — an IMAP APPEND with keywords is one call rather than a POST followed by a PATCH. Flag-shaped keywords ($seen, $answered, $flagged, $draft) fold onto their flag bit.
filterbooleanquery filterWhether to run the mailbox's active Sieve filter on this append (default false)
internaldatenumberquery internaldateOriginal receive timestamp in epoch seconds for migration/import (default now)
envelopeFromstringheader x-envelope-fromEnvelope sender email address
envelopeTostringheader x-envelope-toEnvelope recipient email address
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_header, or message exceeds size limit
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 or not accessible to this principal
411Length Required — Content-Length header is required
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

It names these types of the API, each on a page of its own: AppendResult.