# Save structured message to mailbox

Constructs and saves an email message from structured JSON (headers, body text/HTML, attachments) into a mailbox without sending.

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

### Path parameters

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

### Query parameters

- `label` (string) — Target label (default INBOX)
- `flags` (string) — Comma-separated initial flags, e.g. seen,draft
- `filter` ("true" | "false") — Whether to run the mailbox's active Sieve filter (default false)
- `internaldate` (integer | null, ≥ -62135596800, ≤ 253402300799) — Epoch seconds recorded as receivedAt (default now)

### Header parameters

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

### Request body (required)

`application/json`

- `from` (MailAddress, required)
  - `email` (string, required, 3–320 chars) — Email address (e.g. alice@example.com)
  - `name` (string | null, max 320 chars) — Display name (e.g. Alice Smith)
- `attachments` (object[], max 50 items)
  - `blobId` (string, 1–64 chars) — Staged-upload form: a blobId from POST /mailboxes/{id}/uploads (or JMAP /upload)
  - `content` (string) — Inline form: base64 payload
  - `contentId` (string | null, max 255 chars)
  - `contentType` (string | null, max 255 chars) — Defaults to the stored part's / upload's type for a reference or blob, else application/octet-stream
  - `filename` (string, 1–255 chars) — Required for an inline attachment. For a reference or a staged upload, defaults to the stored part's filename (or "attachment").
  - `messageId` (string, 1–64 chars) — Reference form: a message in THIS mailbox to take the part from
  - `section` (string, max 64 chars, pattern `^[0-9]+(\.[0-9]+)*$`) — Reference form: the part's section, as reported by /messages/{id}/content
- `bcc` (MailAddress[], max 100 items)
  - `email` (string, required, 3–320 chars) — Email address (e.g. alice@example.com)
  - `name` (string | null, max 320 chars) — Display name (e.g. Alice Smith)
- `cc` (MailAddress[], max 100 items)
  - `email` (string, required, 3–320 chars) — Email address (e.g. alice@example.com)
  - `name` (string | null, max 320 chars) — Display name (e.g. Alice Smith)
- `headers` (object) — Extra headers; structural ones (Content-Type, Date, …) are refused
- `html` (string | null) — HTML body; paired with text as multipart/alternative
- `inReplyTo` (string | null, max 512 chars) — Parent Message-ID, angle-bracketed
- `messageId` (string | null, max 998 chars) — Overrides the generated Message-ID
- `references` (string[], max 50 items)
- `replyTo` (MailAddress[], max 10 items)
  - `email` (string, required, 3–320 chars) — Email address (e.g. alice@example.com)
  - `name` (string | null, max 320 chars) — Display name (e.g. Alice Smith)
- `subject` (string | null, max 2000 chars)
- `text` (string | null) — Plain-text body
- `to` (MailAddress[], max 100 items)
  - `email` (string, required, 3–320 chars) — Email address (e.g. alice@example.com)
  - `name` (string | null, max 320 chars) — Display name (e.g. Alice Smith)

### Responses

**200** — Stored (uid + uidValidity answer IMAP APPENDUID), or status:filtered when an opted-in Sieve filter discarded it

`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_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

`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/not accessible, unknown_label, or mailbox_gone

`application/json` → ErrorBody

**411** — Content-Length required

`application/json` → ErrorBody

**413** — JSON body exceeds MAX_JSON_BODY_BYTES, or the assembled message exceeds MAX_MESSAGE_BYTES

`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/compose' \
  -H 'Authorization: Bearer oek_…' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": {
      "email": "string"
    }
  }'
```

## TypeScript SDK

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

```ts
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' }],
})
```
