# messages.compose

Save structured message to mailbox.

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

```ts
openemail.messages.compose(
  mailboxId: string,
  body: MessagesComposeBody,
  options?: MessagesComposeOptions,
): ApiPromise<AppendResult>
```

It calls `POST /mailboxes/{mailboxId}/messages/compose`: [Save structured message to mailbox](/docs/api/messages/post_MessageCompose) in the API reference.

## Example

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

## Arguments

| Argument | Type | Description |
| --- | --- | --- |
| `mailboxId` | `string` | Mailbox ULID identifier. The path's `{mailboxId}`. |
| `body` | [`MessagesComposeBody`](#messagescomposebody) | The request's body. |

## Options

The last argument, `options`, a `MessagesComposeOptions`, takes:

| Option | Type | Sent as | Description |
| --- | --- | --- | --- |
| `label` | `string` | query `label` | Target label (default INBOX) |
| `flags` | `string` | query `flags` | Comma-separated initial flags, e.g. seen,draft |
| `filter` | `boolean` | query `filter` | Whether to run the mailbox's active Sieve filter (default false) |
| `internaldate` | `number` | query `internaldate` | Epoch seconds recorded as receivedAt (default now) |
| `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_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 |
| `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/not accessible, unknown_label, or mailbox_gone |
| `411` | Content-Length required |
| `413` | JSON body exceeds MAX_JSON_BODY_BYTES, or the assembled message exceeds MAX_MESSAGE_BYTES |
| `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

### MessagesComposeBody

```ts
/** The body of `messages.compose`. */
type MessagesComposeBody = {
  attachments?: MessagesComposeBodyAttachmentsItem[]
  bcc?: MailAddress[]
  cc?: MailAddress[]
  from: MailAddress
  /** Extra headers; structural ones (Content-Type, Date, …) are refused */
  headers?: Record<string, string>
  /** HTML body; paired with text as multipart/alternative */
  html?: string | null
  /** Parent Message-ID, angle-bracketed */
  inReplyTo?: string | null
  /** Overrides the generated Message-ID */
  messageId?: string | null
  references?: string[]
  replyTo?: MailAddress[]
  subject?: string | null
  /** Plain-text body */
  text?: string | null
  to?: MailAddress[]
}
```

### MessagesComposeBodyAttachmentsItem

```ts
/** The API's `MessagesComposeBodyAttachmentsItem`, as the document describes it. */
type MessagesComposeBodyAttachmentsItem = {
  /** Staged-upload form: a blobId from POST /mailboxes/{id}/uploads (or JMAP /upload) */
  blobId?: string
  /** Inline form: base64 payload */
  content?: string
  contentId?: string | null
  /** Defaults to the stored part's / upload's type for a reference or blob, else application/octet-stream */
  contentType?: string | null
  /** Required for an inline attachment. For a reference or a staged upload, defaults to the stored part's filename (or "attachment"). */
  filename?: string
  /** Reference form: a message in THIS mailbox to take the part from */
  messageId?: string
  /** Reference form: the part's section, as reported by /messages/{id}/content */
  section?: string
}
```

It names these types of the API, each on a page of its own: [`AppendResult`](/docs/sdks/typescript/types/append-result), [`MailAddress`](/docs/sdks/typescript/types/mail-address).
