messages.append
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
| Argument | Type | Description |
|---|---|---|
mailboxId | string | Mailbox ULID identifier. The path's {mailboxId}. |
message | RawBody | Raw 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:
| Option | Type | Sent as | Description |
|---|---|---|---|
label | string | query label | Target label or folder (default INBOX) |
flags | string | query flags | Comma-separated initial flags, e.g. seen,draft |
keywords | string | query keywords | Comma-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. |
filter | boolean | query filter | Whether to run the mailbox's active Sieve filter on this append (default false) |
internaldate | number | query internaldate | Original receive timestamp in epoch seconds for migration/import (default now) |
envelopeFrom | string | header x-envelope-from | Envelope sender email address |
envelopeTo | string | header x-envelope-to | Envelope recipient email address |
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_header, or message exceeds size limit |
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 or not accessible to this principal |
411 | Length Required — Content-Length header is required |
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
It names these types of the API, each on a page of its own: AppendResult.