# 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.

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

It calls `POST /mailboxes/{mailboxId}/messages`: [Append raw MIME message to mailbox](/docs/api/messages/post_MessageAppend) in the API reference.

## Example

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

## Arguments

| Argument | Type | Description |
| --- | --- | --- |
| `mailboxId` | `string` | Mailbox ULID identifier. The path's `{mailboxId}`. |
| `message` | [`RawBody`](/docs/sdks/typescript/calling-methods#raw-bodies) | Raw RFC 5322 message bytes. The request's body, as bytes: text, a `Blob`, an `ArrayBuffer` or a `Uint8Array` ([raw bodies](/docs/sdks/typescript/calling-methods#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](/docs/sdks/typescript/calling-methods#call-options)).

## Answer

Awaited, it is the API's JSON, [`AppendResult`](/docs/sdks/typescript/types/append-result). It is an [`ApiPromise`](/docs/sdks/typescript/responses): `.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](/docs/sdks/typescript/errors#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`](/docs/sdks/typescript/errors): 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`](/docs/sdks/typescript/types/append-result).
