# List drafts

GET /v1/inboxes/{inbox_id}/drafts

Source: https://cherami.to/docs/api/drafts/list-drafts



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

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

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

Returns `200` with `{"drafts":[...],"next_cursor":null}`. Entries contain draft metadata without creation-key fields. `state` is `draft` (default), `submitted` or `all`. Results are newest-created first. `limit` is 1–100, default 20; use the returned opaque `cursor` with the same inbox and state. This is a live listing, not a snapshot. Drafts do not appear in received/sent mail search or conversations before submission.

Unsupported or repeated query parameters and malformed or mismatched cursors return `400 invalid_draft`; an invalid limit returns `400 invalid_limit`.

## Parameters [#parameters]

| Parameter  | Location | Required | Type                                  | Meaning                                                                                                                                |
| ---------- | -------- | -------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `inbox_id` | path     | Yes      | string                                | Owned Cherami resource ID returned by the API.                                                                                         |
| `limit`    | query    | No       | integer                               | Decimal integer without signs, whitespace or leading zeroes. `minimum`: `1` `maximum`: `100` `default`: `20`                           |
| `cursor`   | query    | No       | string                                | Opaque returned cursor. Keep resource URL, filters and ordering unchanged; stop when next\_cursor is null.                             |
| `state`    | query    | No       | `"draft"` or `"submitted"` or `"all"` | Include submitted drafts when reconciling uncertain creation. Only limit, cursor and state are accepted, each once. `default`: `draft` |

## curl example [#curl-example]

Replace resource-ID placeholders with returned IDs. Supply `CHERAMI_API_KEY` through your private shell environment.

```sh
curl --silent --show-error --include --request GET \
  "https://cherami.to/v1/inboxes/INBOX_ID/drafts" \
  --header "Authorization: Bearer $CHERAMI_API_KEY"
```

## Responses [#responses]

### HTTP 200 [#http-200]

Successful operation; inspect resource state and outcome fields.

* `X-Request-ID`: Support correlation ID, not an idempotency key.

Content type: `application/json`.

| Field         | Required | Type                                            | Meaning and constraints |
| ------------- | -------- | ----------------------------------------------- | ----------------------- |
| `drafts`      | Yes      | array of [DraftMetadata](#schema-draftmetadata) |                         |
| `next_cursor` | Yes      | string or null                                  |                         |

```json
{
  "drafts": [],
  "next_cursor": null
}
```

### HTTP 400 [#http-400]

`invalid_limit`: Use an integer from 1 to 100.

`invalid_draft`: Use supported draft fields, source preparation or listing parameters. Draft cursors that are malformed or do not match the inbox/state also use this code.

* `X-Request-ID`: Support correlation ID, not an idempotency key.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 401 [#http-401]

`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.

* `X-Request-ID`: Support correlation ID, not an idempotency key.
* `WWW-Authenticate`: `"Bearer"`

Content type: `application/json`.

[Error](#schema-error)

### HTTP 404 [#http-404]

`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.

* `X-Request-ID`: Support correlation ID, not an idempotency key.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 503 [#http-503]

`draft_unavailable`: Draft operation is uncertain. Follow [draft-specific recovery](https://cherami.to/docs/api/drafts); do not blindly create a replacement.

* `X-Request-ID`: Support correlation ID, not an idempotency key.

Content type: `application/json`.

[Error](#schema-error)

## Schema: DraftMetadata [#schema-draftmetadata]

| Field             | Required | Type                       | Meaning and constraints                                                                                                              |
| ----------------- | -------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `id`              | Yes      | string                     | Cherami resource ID, distinct from the RFC Message-ID. Use the returned value.                                                       |
| `inbox_id`        | Yes      | string                     | Cherami resource ID, distinct from the RFC Message-ID. Use the returned value.                                                       |
| `state`           | Yes      | `"draft"` or `"submitted"` |                                                                                                                                      |
| `subject`         | Yes      | string                     |                                                                                                                                      |
| `created_at`      | Yes      | string                     | UTC service instant with milliseconds and Z suffix. `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 service instant with milliseconds and Z suffix. `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             |                                                                                                                                      |

## 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 | Programmatic error code. Handle unrecognized codes by status and operation-specific recovery. |
| `message` | Yes      | string | Human-readable context, not a stable string to match.                                         |

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