# Create a draft

POST /v1/inboxes/{inbox_id}/drafts

Source: https://cherami.to/docs/api/drafts/create-draft



{/* Generated from apps/web/openapi. Edit the contract, not this file. */}

`POST /v1/inboxes/{inbox_id}/drafts`

Requires an [API key](https://cherami.to/docs/api#authentication): `Authorization: Bearer YOUR_CREDENTIAL`.

Saves a message in the inbox to finish, review or [send](https://cherami.to/docs/api/drafts/send-draft) later. Saving uses no sending allowance. Every field is optional (`{}` saves an empty draft) and takes the formats and limits of [send](https://cherami.to/docs/api/sending/send-message); recipients, subject and text are checked when you send. Creation returns metadata only: [retrieve the draft](https://cherami.to/docs/api/drafts/get-draft) for its content.

### Prepare a reply or forward [#prepare-a-reply-or-forward]

Set `source` to an `action` (`reply`, `reply-all` or `forward`) and a `message_id`, a ready received message or an accepted sent message in this inbox, to have Cherami fill in the draft once, at creation:

* `reply` and `reply-all` save the recipients, subject and `in_reply_to` derived as for [reply](https://cherami.to/docs/api/sending/reply-message) and [reply-all](https://cherami.to/docs/api/sending/reply-all-message). Fields you supply override them, including an empty array or a null `in_reply_to`. Your `text` and `attachments` make up the reply; no history or original files are copied. The message you reply to must still exist when you send, and changing `in_reply_to` later doesn't re-derive recipients or subject.
* `forward` saves the full forward as text and HTML, with your `text` as the note, plus the original attachments unless `source.include_attachments` is `false`. Add recipients now or later. `attachments` can't be supplied with a forward source; edit the draft afterwards to change its files.

### Recover creation [#recover-creation]

Include an `idempotency_key` to make a retry safe. If creation is uncertain, repeat the exact request with the same key within 24 hours of your first attempt: a match returns `200` with `replayed: true` and the draft's current metadata, without applying the payload again.

After 24 hours, or without a key, [list drafts](https://cherami.to/docs/api/drafts/list-drafts) with `state=all` before creating again: a blind repeat makes a duplicate.

## Parameters [#parameters]

| Parameter  | Location | Required | Type   | Meaning                                  |
| ---------- | -------- | -------- | ------ | ---------------------------------------- |
| `inbox_id` | path     | Yes      | string | Cherami resource ID returned by the API. |

## Request body [#request-body]

JSON object, at most 8 MiB in total.

### Schema: CreateDraft [#schema-createdraft]

| Field             | Required | Type                                                        | Meaning and constraints                                                                                                                                                                                                                       |
| ----------------- | -------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `to`              | No       | array of [Mailbox](#schema-mailbox)                         | `maxItems`: `50`                                                                                                                                                                                                                              |
| `cc`              | No       | array of [Mailbox](#schema-mailbox)                         | `maxItems`: `50`                                                                                                                                                                                                                              |
| `bcc`             | No       | array of [Mailbox](#schema-mailbox)                         | `maxItems`: `50`                                                                                                                                                                                                                              |
| `subject`         | No       | string                                                      | No control characters; at most 998 UTF-8 bytes. `x-max-utf8-bytes`: `998`                                                                                                                                                                     |
| `text`            | No       | string                                                      | Plain-text body.                                                                                                                                                                                                                              |
| `html`            | No       | string or null                                              | HTML alternative, sent as supplied; null means none.                                                                                                                                                                                          |
| `attachments`     | No       | array of [AttachmentInput](#schema-attachmentinput) or null | Omitted, null or \[] means no attachments.                                                                                                                                                                                                    |
| `in_reply_to`     | No       | string or null                                              | ID of a ready received message or an accepted sent message in this inbox that has a Message-ID header; null means none.                                                                                                                       |
| `labels`          | No       | array of [Label](#schema-label)                             | Label names, case-sensitive; order and duplicates don't matter. `maxItems`: `32`                                                                                                                                                              |
| `idempotency_key` | No       | string                                                      | Your unique value for this one operation. Save it with the exact request before sending; repeating that request with the same key within 24 hours returns what the first one did instead of acting again. `pattern`: `^[A-Za-z0-9_-]{1,128}$` |
| `source`          | No       | object or object                                            | Fills in the draft once, at creation, as a reply, reply-all or forward of message\_id.                                                                                                                                                        |

Unknown fields are rejected.

#### `source` fields [#source-fields]

Fills in the draft once, at creation, as a reply, reply-all or forward of message\_id.

Exactly one of these shapes applies.

##### Alternative 1 [#alternative-1]

| Field        | Required | Type                       | Meaning and constraints                                                                                |
| ------------ | -------- | -------------------------- | ------------------------------------------------------------------------------------------------------ |
| `action`     | Yes      | `"reply"` or `"reply-all"` |                                                                                                        |
| `message_id` | Yes      | string                     | ID of a ready received message or an accepted sent message in this inbox. `pattern`: `^[a-f0-9-]{36}$` |

Unknown fields are rejected.

##### Alternative 2 [#alternative-2]

| Field                 | Required | Type        | Meaning and constraints                                                                                |
| --------------------- | -------- | ----------- | ------------------------------------------------------------------------------------------------------ |
| `action`              | Yes      | `"forward"` |                                                                                                        |
| `message_id`          | Yes      | string      | ID of a ready received message or an accepted sent message in this inbox. `pattern`: `^[a-f0-9-]{36}$` |
| `include_attachments` | No       | boolean     | false leaves out every original file, embedded images included. `default`: `true`                      |

Unknown fields are rejected.

## curl example [#curl-example]

Supply `CHERAMI_API_KEY` privately.

Save the payload as `request.json`, replacing the example values.

```json
{
  "subject": "Proposal for review",
  "text": "Draft proposal.",
  "idempotency_key": "RETAIN_A_UNIQUE_CREATION_KEY"
}
```

```sh
curl --silent --show-error --include --request POST \
  "https://cherami.to/v1/inboxes/INBOX_ID/drafts" \
  --header "Authorization: Bearer $CHERAMI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @request.json
```

## Responses [#responses]

### HTTP 200 [#http-200]

A retry matched an earlier request: this is that request's result as it is now. Nothing new was created or sent.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.
* `Location`: Relative URL of the resulting resource.

Content type: `application/json`.

All of these schemas apply.

### Part 1 [#part-1]

[CreatedDraft](#schema-createddraft)

### Part 2 [#part-2]

| Field                    | Required | Type   | Meaning and constraints                                                                                                 |
| ------------------------ | -------- | ------ | ----------------------------------------------------------------------------------------------------------------------- |
| `replayed`               | Yes      | `true` |                                                                                                                         |
| `idempotency_expires_at` | Yes      | string | When the key stops protecting retries. `format`: `date-time` `pattern`: `^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$` |

```json
{
  "id": "11111111-1111-4111-8111-111111111111",
  "inbox_id": "11111111-1111-4111-8111-111111111111",
  "state": "draft",
  "subject": "Example",
  "created_at": "2026-10-01T00:00:00.000Z",
  "updated_at": "2026-10-01T00:00:00.000Z",
  "sent_message_id": null,
  "replayed": true,
  "idempotency_expires_at": "2026-10-02T00:00:00.000Z"
}
```

### HTTP 201 [#http-201]

Created.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.
* `Location`: Relative URL of the resulting resource.

Content type: `application/json`.

All of these schemas apply.

### Part 1 [#part-1-1]

[CreatedDraft](#schema-createddraft)

### Part 2 [#part-2-1]

| Field      | Required | Type    | Meaning and constraints |
| ---------- | -------- | ------- | ----------------------- |
| `replayed` | No       | `false` |                         |

### HTTP 400 [#http-400]

`invalid_json`: Send a valid UTF-8 JSON object, not an array or scalar.

`invalid_draft`: Correct the draft field, `source` or listing parameter the message names.

`invalid_message`: Correct the recipients, subject, body, `in_reply_to`, attachments or reply and forward fields as the message describes.

`invalid_name`: Use plain text without control characters, at most 256 UTF-8 bytes after trimming. The message names the field.

`invalid_labels`: Correct the label name, label change, filter group or discovery prefix the message names.

`invalid_idempotency_key`: Use 1–128 ASCII letters, digits, hyphens or underscores.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 401 [#http-401]

`unauthorized`: Send a valid API key as `Authorization: Bearer <key>`. If the key stopped working, get a new one through [recovery](https://cherami.to/docs/guides/recovery).

* `X-Request-ID`: Identifies this request; include it when reporting a problem.
* `WWW-Authenticate`: `"Bearer"`

Content type: `application/json`.

[Error](#schema-error)

### HTTP 404 [#http-404]

`not_found`: The resource does not exist or does not belong to this account. A reply or forward source must also be in the sending inbox.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 409 [#http-409]

`idempotency_conflict`: The key was first used with different input. To recover that request, repeat it with its original inbox and payload; a different request needs its own key.

`idempotency_result_unavailable`: The key already created an inbox, draft or send whose result has since been deleted. Nothing new was created or sent; do not repeat the request under a new key. If a sent message is still in Trash, restore it to read the outcome.

`reply_not_ready`: The source cannot be replied to or forwarded yet. A received message must have `processing_status` `ready`; a sent message must have `status` `accepted`.

`reply_recipients_unavailable`: No recipients remain once the sending inbox is excluded. Send a new message to recipients the task authorizes.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 413 [#http-413]

`body_too_large`: Reduce the JSON request to the operation's body limit.

`message_too_large`: The message exceeds 5 MiB counting text, HTML and base64 attachment content, or a forwarded original has more than 32 attachments. Reduce the content or attachments; for a forward, set `include_attachments` to false or attach selected files to a new message.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 415 [#http-415]

`unsupported_media_type`: Send `Content-Type: application/json`.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 503 [#http-503]

`content_unavailable`: Stored content could not be read. Retry later.

`draft_unavailable`: The draft request failed. Repeat a draft send with the same draft ID: it never sends twice. Repeat a creation with its original idempotency key and payload; without a key, list drafts first. Read the draft before repeating an edit. Retry a read or a deletion.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Error](#schema-error)

## Schema: CreatedDraft [#schema-createddraft]

| Field                    | Required | Type                       | Meaning and constraints                                                                                                 |
| ------------------------ | -------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `id`                     | Yes      | string                     | Cherami resource ID.                                                                                                    |
| `inbox_id`               | Yes      | string                     | Cherami resource ID.                                                                                                    |
| `state`                  | Yes      | `"draft"` or `"submitted"` |                                                                                                                         |
| `subject`                | Yes      | string                     |                                                                                                                         |
| `created_at`             | Yes      | string                     | UTC timestamp with milliseconds. `format`: `date-time` `pattern`: `^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$`       |
| `updated_at`             | Yes      | string                     | UTC timestamp with milliseconds. `format`: `date-time` `pattern`: `^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$`       |
| `sent_message_id`        | Yes      | string or null             |                                                                                                                         |
| `replayed`               | No       | boolean                    | true when a retry matched an earlier request: the result is that request's, and nothing new was created or sent.        |
| `idempotency_expires_at` | No       | string                     | When the key stops protecting retries. `format`: `date-time` `pattern`: `^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$` |

## Schema: Error [#schema-error]

| Field   | Required | Type   | Meaning and constraints |
| ------- | -------- | ------ | ----------------------- |
| `error` | Yes      | object |                         |

### `error` fields [#error-fields]

| Field     | Required | Type   | Meaning and constraints                                               |
| --------- | -------- | ------ | --------------------------------------------------------------------- |
| `code`    | Yes      | string | Code to handle. Handle a code you don't recognize by its HTTP status. |
| `message` | Yes      | string | Explanation of this case; its wording can change.                     |

## Schema: Mailbox [#schema-mailbox]

| Field     | Required | Type   | Meaning and constraints                                                                                                                 |
| --------- | -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------- |
| `address` | Yes      | string | Bare address such as [alex@example.com](mailto:alex@example.com): ASCII, at most 254 characters and 64 before the @. `maxLength`: `254` |
| `name`    | No       | string | Optional name; blank means none. At most 256 UTF-8 bytes after trimming, without control characters. `x-max-utf8-bytes`: `256`          |

Unknown fields are rejected.

## Schema: AttachmentInput [#schema-attachmentinput]

| Field      | Required | Type   | Meaning and constraints                                                                                                 |
| ---------- | -------- | ------ | ----------------------------------------------------------------------------------------------------------------------- |
| `filename` | Yes      | string | At most 255 UTF-8 bytes, without control characters, slashes or backslashes. `minLength`: `1` `x-max-utf8-bytes`: `255` |
| `type`     | Yes      | string | MIME type without parameters. `maxLength`: `127` `pattern`: `^[A-Za-z0-9!#$&^_.+-]+/[A-Za-z0-9!#$&^_.+-]+$`             |
| `content`  | Yes      | string | The file's bytes as padded base64, without line breaks. `contentEncoding`: `base64` `pattern`: `^[A-Za-z0-9+/]*={0,2}$` |

Unknown fields are rejected.

## Schema: Label [#schema-label]

1–128 UTF-8 bytes after trimming, without control characters; case-sensitive.

string. `x-max-utf8-bytes`: `128`

[Errors, limits and pagination](https://cherami.to/docs/api/errors) · [Download OpenAPI 3.1](https://cherami.to/openapi.json)
