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

## `POST /api/v1/mailboxes/{mailboxId}/messages`

### Path parameters

- `mailboxId` (string, required) — Mailbox ULID identifier

### Query parameters

- `label` (string) — Target label or folder (default INBOX)
- `flags` (string) — Comma-separated initial flags, e.g. seen,draft
- `keywords` (string, max 2048 chars) — 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` ("true" | "false") — Whether to run the mailbox's active Sieve filter on this append (default false)
- `internaldate` (integer | null, ≥ -62135596800, ≤ 253402300799) — Original receive timestamp in epoch seconds for migration/import (default now)

### Header parameters

- `x-envelope-from` (string) — Envelope sender email address
- `x-envelope-to` (string) — Envelope recipient email address
- `x-delivery-id` (string) — 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.
- `content-length` (string) — Message payload size in bytes (required)

### Request body (required)

`message/rfc822`

Type: string

### Responses

**200** — Message appended successfully

`application/json` → AppendResult

- _option 1: object_
  - `duplicate` (boolean, required) — True if message was already delivered previously
  - `messageId` (string, required) — Assigned message ULID
  - `status` ("delivered", required) — Message was successfully delivered and stored
  - `threadId` (string | null, required) — Assigned conversation thread ULID, or null on duplicate
  - `uid` (integer | null, required) — Assigned message UID, or null on duplicate
  - `uidValidity` (integer | null, required) — Label UID validity epoch, or null on duplicate
  - `blobHash` (string) — On a fresh store: the blob SHA-256 (what body caches key on)
  - `flags` (string[]) — On a fresh store: the flags the row was stored with
  - `keywords` (string[]) — On a fresh store: the keywords the row was stored with
  - `modseq` (integer <int64>) — On a fresh store: the membership row's MODSEQ in the target label
  - `receivedAt` (integer <int64>) — On a fresh store: the INTERNALDATE in epoch seconds
  - `size` (integer <int64>) — On a fresh store: the stored size in bytes
- _option 2: object_
  - `deliveryId` (string, required) — The STORED delivery key: any supplied X-Delivery-Id namespaced into the `append:` import family (so an append is never mistaken for an arrival). Correlates with the traffic log's delivery_id; retry with the ORIGINAL X-Delivery-Id, not this value.
  - `redirected` (boolean, required) — True if message was forwarded/redirected by rule
  - `status` ("filtered", required) — Message was processed by a Sieve rule action

**400** — validation_failed, invalid_header, or message exceeds size limit

`application/json` → ErrorOrValidation

**401** — unauthorized: the bearer credential is missing, malformed, expired, or revoked. Carries a `WWW-Authenticate: Bearer` challenge

`application/json` → ErrorBody

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

`application/json` → ErrorBody

**404** — Mailbox not found or not accessible to this principal

`application/json` → ErrorBody

**411** — Length Required — Content-Length header is required

`application/json` → ErrorBody

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

`application/json` → ErrorBody

**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)

`application/json` → ErrorBody

**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

`application/json` → ErrorBody

### Example request

```bash
curl -X POST 'https://api.open.email/api/v1/mailboxes/{mailboxId}/messages' \
  -H 'Authorization: Bearer oek_…' \
  -H 'Content-Type: message/rfc822'
```

## TypeScript SDK

[`openemail.messages.append`](/docs/sdks/typescript/messages/append)

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