--- title: "Drafts" description: "Every operation in this group: what it accepts, what it returns and the errors it can answer with." url: "https://nextmail.sh/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` `DraftList`: A page of drafts. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors). Also available in: TypeScript [`nextmail.drafts.list()`](https://nextmail.sh/docs/sdk/reference/drafts#list), [`nextmail.drafts.listAll()`](https://nextmail.sh/docs/sdk/reference/drafts#listAll), [`nextmail.drafts.iterate()`](https://nextmail.sh/docs/sdk/reference/drafts#iterate); Python [`drafts.list()`](https://nextmail.sh/docs/python/reference/drafts#list), [`drafts.list_all()`](https://nextmail.sh/docs/python/reference/drafts#listAll), [`drafts.iterate()`](https://nextmail.sh/docs/python/reference/drafts#iterate); Ruby [`drafts.list`](https://nextmail.sh/docs/ruby/reference/drafts#list), [`drafts.list_all`](https://nextmail.sh/docs/ruby/reference/drafts#listAll), [`drafts.iterate`](https://nextmail.sh/docs/ruby/reference/drafts#iterate); PHP [`drafts->list`](https://nextmail.sh/docs/php/reference/drafts#list), [`drafts->listAll`](https://nextmail.sh/docs/php/reference/drafts#listAll), [`drafts->iterate`](https://nextmail.sh/docs/php/reference/drafts#iterate); Go [`Drafts.List`](https://nextmail.sh/docs/go/reference/drafts#list), [`Drafts.ListAll`](https://nextmail.sh/docs/go/reference/drafts#listAll), [`Drafts.Iterate`](https://nextmail.sh/docs/go/reference/drafts#iterate); Java [`drafts().list`](https://nextmail.sh/docs/java/reference/drafts#list), [`drafts().listAll`](https://nextmail.sh/docs/java/reference/drafts#listAll), [`drafts().iterate`](https://nextmail.sh/docs/java/reference/drafts#iterate); C# [`Drafts.ListAsync`](https://nextmail.sh/docs/csharp/reference/drafts#list), [`Drafts.ListAllAsync`](https://nextmail.sh/docs/csharp/reference/drafts#listAll), [`Drafts.IterateAsync`](https://nextmail.sh/docs/csharp/reference/drafts#iterate); CLI [`nextmail drafts list`](https://nextmail.sh/docs/cli/reference/drafts#drafts-list); MCP [`listDrafts`](https://nextmail.sh/docs/mcp/tools/drafts#listDrafts). ### `POST /drafts` Create a draft Saves a draft without sending it, as the composer does when you close it. Every field is optional, and `html` wins over `text` when both are given. To forward an email, pass `threadId` and `forwardOf`, the id of a message in that thread from `GET /threads/{id}`. The draft takes the names of that message's files and, unless you give a `subject`, the message's subject with `Fwd:` in front. Sending it with `draftId` on `POST /emails` quotes the message below the body, attaches its files and threads it the way forwarding in the app does. `forwardOf` without `threadId`, or naming no message of that thread, is a 422 `invalid_parameter`. Requires the `drafts:write` scope. - Scopes: `drafts:write`. **Request body** - `to` (`string[]`, default `[]`): Recipient addresses, bare or with a display name. - `cc` (`string[]`, default `[]`): Copy recipients, bare or with a display name. - `bcc` (`string[]`, default `[]`): Blind copy recipients, bare or with a display name. - `subject` (`string`, up to 998 characters, default `""`): At most 998 characters. Empty is stored as `(no subject)`. - `html` (`string`, up to 1000000 characters): Body markup, at most 1,000,000 characters. Kept over `text` when both are set. - `text` (`string`, up to 1000000 characters): Body used only when `html` is absent, at most 1,000,000 characters. Stored as is and read back in `html`. - `from` (`string`): The address it will be sent from. A key or an app limited to particular addresses has to name one of them, and one it may send as. - `threadId` (`string`): The conversation it replies to, when it is a reply, or the one holding the message `forwardOf` names. - `forwardOf` (`string`, 1 to 998 characters): The id of the message in `threadId` to forward. Sending the draft quotes it below the body and attaches its files. **Returns** - `201` `DraftReference`: Created. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors). Also available in: TypeScript [`nextmail.drafts.create()`](https://nextmail.sh/docs/sdk/reference/drafts#create); Python [`drafts.create()`](https://nextmail.sh/docs/python/reference/drafts#create); Ruby [`drafts.create`](https://nextmail.sh/docs/ruby/reference/drafts#create); PHP [`drafts->create`](https://nextmail.sh/docs/php/reference/drafts#create); Go [`Drafts.Create`](https://nextmail.sh/docs/go/reference/drafts#create); Java [`drafts().create`](https://nextmail.sh/docs/java/reference/drafts#create); C# [`Drafts.CreateAsync`](https://nextmail.sh/docs/csharp/reference/drafts#create); CLI [`nextmail drafts create`](https://nextmail.sh/docs/cli/reference/drafts#drafts-create); MCP [`createDraft`](https://nextmail.sh/docs/mcp/tools/drafts#createDraft), [`updateDraft`](https://nextmail.sh/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` `Draft`: The draft. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors). Also available in: TypeScript [`nextmail.drafts.get()`](https://nextmail.sh/docs/sdk/reference/drafts#get); Python [`drafts.get()`](https://nextmail.sh/docs/python/reference/drafts#get); Ruby [`drafts.get`](https://nextmail.sh/docs/ruby/reference/drafts#get); PHP [`drafts->get`](https://nextmail.sh/docs/php/reference/drafts#get); Go [`Drafts.Get`](https://nextmail.sh/docs/go/reference/drafts#get); Java [`drafts().get`](https://nextmail.sh/docs/java/reference/drafts#get); C# [`Drafts.GetAsync`](https://nextmail.sh/docs/csharp/reference/drafts#get); CLI [`nextmail drafts get`](https://nextmail.sh/docs/cli/reference/drafts#drafts-get); MCP [`getDraft`](https://nextmail.sh/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. Its attachments stay as they are, and a draft that forwards a message keeps forwarding it unless `threadId` moves it to another conversation. Requires the `drafts:write` scope. - Scopes: `drafts:write`. **Path parameters** - `id` (`string`, required): Draft id, which starts with `draft-`. **Request body** - `to` (`string[]`): Replacement recipients. An empty array clears them. - `cc` (`string[]`): Replacement copy recipients. - `bcc` (`string[]`): Replacement blind copy recipients. - `subject` (`string`, up to 998 characters): Replacement subject, at most 998 characters. - `html` (`string`, up to 1000000 characters): Replacement body markup, at most 1,000,000 characters. - `text` (`string`, up to 1000000 characters): Replacement body used only when `html` is absent. - `from` (`string`, nullable): The address it will be sent from, or null to clear it. A key or an app limited to particular addresses has to name one of them. - `threadId` (`string`): The conversation it replies to. **Returns** - `200` `DraftReference`: Saved. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors). Also available in: TypeScript [`nextmail.drafts.update()`](https://nextmail.sh/docs/sdk/reference/drafts#update); Python [`drafts.update()`](https://nextmail.sh/docs/python/reference/drafts#update); Ruby [`drafts.update`](https://nextmail.sh/docs/ruby/reference/drafts#update); PHP [`drafts->update`](https://nextmail.sh/docs/php/reference/drafts#update); Go [`Drafts.Update`](https://nextmail.sh/docs/go/reference/drafts#update); Java [`drafts().update`](https://nextmail.sh/docs/java/reference/drafts#update); C# [`Drafts.UpdateAsync`](https://nextmail.sh/docs/csharp/reference/drafts#update); CLI [`nextmail drafts update`](https://nextmail.sh/docs/cli/reference/drafts#drafts-update); MCP [`createDraft`](https://nextmail.sh/docs/mcp/tools/drafts#createDraft), [`updateDraft`](https://nextmail.sh/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` `DeletedDraft`: Deleted. **Errors** - The errors every operation can return: `400`, `401`, `403`, `404`, `422`, `429`, `500`, described in the [error catalog](https://nextmail.sh/docs/api/errors). Also available in: TypeScript [`nextmail.drafts.delete()`](https://nextmail.sh/docs/sdk/reference/drafts#delete); Python [`drafts.delete()`](https://nextmail.sh/docs/python/reference/drafts#delete); Ruby [`drafts.delete`](https://nextmail.sh/docs/ruby/reference/drafts#delete); PHP [`drafts->delete`](https://nextmail.sh/docs/php/reference/drafts#delete); Go [`Drafts.Delete`](https://nextmail.sh/docs/go/reference/drafts#delete); Java [`drafts().delete`](https://nextmail.sh/docs/java/reference/drafts#delete); C# [`Drafts.DeleteAsync`](https://nextmail.sh/docs/csharp/reference/drafts#delete); CLI [`nextmail drafts delete`](https://nextmail.sh/docs/cli/reference/drafts#drafts-delete); MCP [`deleteDraft`](https://nextmail.sh/docs/mcp/tools/drafts#deleteDraft). ### Objects #### `DeletedDraft` `object` - `object` (`string`, required, one of `"draft"`) - `id` (`string`, required) - `deleted` (`boolean`, required, one of `true`) #### `Draft` `object` - `object` (`string`, required, one of `"draft"`) - `id` (`string`, required) - `to` (`string[]`, required) - `cc` (`string[]`, required) - `bcc` (`string[]`, required) - `subject` (`string`, required) - `html` (`string`, required): The body as saved. - `threadId` (`string`, required, nullable): The conversation it replies to, when it is a reply. - `forwardOf` (`string`, required, nullable): The message in `threadId` this draft forwards, or null. Sending the draft quotes that message below the body and attaches its files, one for each file the draft lists. - `from` (`string`, required, nullable): The sending address. Null when none is set or it is not one this workspace can send as. - `attachments` (`object[]`, required) - `filename` (`string`, required, nullable) - `contentType` (`string`, required, nullable) - `size` (`integer`, required, nullable): Size in bytes, when known. #### `DraftList` `object` - `object` (`string`, required, one of `"list"`) - `data` (`DraftReference[]`, required) - `nextPageToken` (`string`, required, nullable): Pass it back as `pageToken` for the next page. Null on the last page. #### `DraftReference` `object` - `object` (`string`, required, one of `"draft"`) - `id` (`string`, required)