---
title: "Drafts"
description: "Every operation in this group: what it accepts, what it returns and the errors it can answer with."
url: "https://openemail.uk/docs/api/reference/drafts"
area: "API"
category: "Reference"
---

# Drafts

Every operation in this group: what it accepts, what it returns and the errors it can answer with.

## Operations

### `GET /drafts`

List drafts

Requires the `drafts:read` scope.

- Scopes: `drafts:read`.

**Query parameters**

- `query` (`string`): The same search syntax as `GET /threads`, read against each draft's subject, sender and the first 4,000 characters of its body. Plain words match loosely and a quoted phrase has to appear as written, filler words are dropped when something else is left to search for, and a value the search cannot use is ignored rather than narrowing. Recipients are not searched, so `to:`, `cc:` and `bcc:` match nothing here. The drafts folder always applies, so `in:` and folder `is:` operators cannot widen the search beyond drafts, `in:anywhere` included. A draft saved with no subject is stored as `(no subject)`, so `subject:"no subject"` finds it.
- `limit` (`integer`, at least 1, at most 100): Drafts per page, a whole number from 1 to 100. Defaults to 25.
- `pageToken` (`string`): Opaque. Pass back what you were given, never construct one.

**Returns**

- `200`: A page of drafts.

**Errors**

- The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors).

Also available in: SDK [`drafts.list()`](https://openemail.uk/docs/sdk/reference/drafts#list), [`drafts.listAll()`](https://openemail.uk/docs/sdk/reference/drafts#listAll), [`drafts.iterate()`](https://openemail.uk/docs/sdk/reference/drafts#iterate); CLI [`openemail drafts list`](https://openemail.uk/docs/cli/reference/drafts#drafts-list); MCP [`listDrafts`](https://openemail.uk/docs/mcp/tools/drafts#listDrafts).

### `POST /drafts`

Create a draft

Requires the `drafts:write` scope.

- Scopes: `drafts:write`.

**Returns**

- `201`: Created.

**Errors**

- The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors).

Also available in: SDK [`drafts.create()`](https://openemail.uk/docs/sdk/reference/drafts#create); CLI [`openemail drafts create`](https://openemail.uk/docs/cli/reference/drafts#drafts-create); MCP [`createDraft`](https://openemail.uk/docs/mcp/tools/drafts#createDraft), [`updateDraft`](https://openemail.uk/docs/mcp/tools/drafts#updateDraft).

### `GET /drafts/{id}`

Retrieve a draft

Requires the `drafts:read` scope.

- Scopes: `drafts:read`.

**Path parameters**

- `id` (`string`, required): Draft id, which starts with `draft-`.

**Returns**

- `200`: The draft.

**Errors**

- The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors).

Also available in: SDK [`drafts.get()`](https://openemail.uk/docs/sdk/reference/drafts#get); CLI [`openemail drafts get`](https://openemail.uk/docs/cli/reference/drafts#drafts-get); MCP [`getDraft`](https://openemail.uk/docs/mcp/tools/drafts#getDraft).

### `PATCH /drafts/{id}`

Update a draft

A partial update, not an upsert. An unknown id, or the id of a thread that is not a draft, is a 404. The draft keeps the id you passed, and the response echoes it.

Requires the `drafts:write` scope.

- Scopes: `drafts:write`.

**Path parameters**

- `id` (`string`, required): Draft id, which starts with `draft-`.

**Returns**

- `200`: Saved.

**Errors**

- The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors).

Also available in: SDK [`drafts.update()`](https://openemail.uk/docs/sdk/reference/drafts#update); CLI [`openemail drafts update`](https://openemail.uk/docs/cli/reference/drafts#drafts-update); MCP [`createDraft`](https://openemail.uk/docs/mcp/tools/drafts#createDraft), [`updateDraft`](https://openemail.uk/docs/mcp/tools/drafts#updateDraft).

### `DELETE /drafts/{id}`

Delete a draft

Requires the `drafts:write` scope.

- Scopes: `drafts:write`.

**Path parameters**

- `id` (`string`, required): Draft id, which starts with `draft-`.

**Returns**

- `200`: Deleted.

**Errors**

- The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `500`, described in the [error catalog](https://openemail.uk/docs/api/errors).

Also available in: SDK [`drafts.delete()`](https://openemail.uk/docs/sdk/reference/drafts#delete); CLI [`openemail drafts delete`](https://openemail.uk/docs/cli/reference/drafts#drafts-delete); MCP [`deleteDraft`](https://openemail.uk/docs/mcp/tools/drafts#deleteDraft).