--- title: "Chats" 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/chats" area: "API" category: "Reference" --- # Chats Every operation in this group: what it accepts, what it returns and the errors it can answer with. ## Operations The conversations held with the assistant in the app, as the Chats page lists them. Each person reaches only their own chats: an API key reaches the chats of the workspace owner, and an app reaches the chats of the person who connected it. A key or an app limited to particular addresses or domains is a 422 `capability_unsupported`. ### `GET /chats` List the assistant chats Your chats, newest first, a page at a time, each with its title, how many messages it holds and when it last changed. `q` searches the titles and `sort` orders them. Each person reaches only their own chats: an API key reaches the chats of the workspace owner, and an app reaches the chats of the person who connected it. A key or an app limited to particular addresses or domains is a 422 `capability_unsupported`. Requires the `threads:read` scope. - Scopes: `threads:read`. **Query parameters** - `q` (`string`, up to 200 characters): Search the titles. - `sort` (`string`, one of `"newest"`, `"oldest"`, `"title"`, default `"newest"`): `newest` and `oldest` order by the last change, and `title` alphabetically. - `limit` (`integer`, at least 1, at most 100, default `25`): Rows per page, 1 to 100. - `cursor` (`string`): The previous page's `nextCursor`, passed back as it came. It is opaque: it holds where the last row sat in this list's order, so a row deleted or edited between pages never breaks the walk, and the next page starts at the first row that sorts after it. A value this list did not hand out is a 400 `invalid_cursor`. **Returns** - `200` `ChatList`: A page of chats. **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.chats.list()`](https://nextmail.sh/docs/sdk/reference/chats#list), [`nextmail.chats.listAll()`](https://nextmail.sh/docs/sdk/reference/chats#listAll), [`nextmail.chats.iterate()`](https://nextmail.sh/docs/sdk/reference/chats#iterate); Python [`chats.list()`](https://nextmail.sh/docs/python/reference/chats#list), [`chats.list_all()`](https://nextmail.sh/docs/python/reference/chats#listAll), [`chats.iterate()`](https://nextmail.sh/docs/python/reference/chats#iterate); Ruby [`chats.list`](https://nextmail.sh/docs/ruby/reference/chats#list), [`chats.list_all`](https://nextmail.sh/docs/ruby/reference/chats#listAll), [`chats.iterate`](https://nextmail.sh/docs/ruby/reference/chats#iterate); PHP [`chats->list`](https://nextmail.sh/docs/php/reference/chats#list), [`chats->listAll`](https://nextmail.sh/docs/php/reference/chats#listAll), [`chats->iterate`](https://nextmail.sh/docs/php/reference/chats#iterate); Go [`Chats.List`](https://nextmail.sh/docs/go/reference/chats#list), [`Chats.ListAll`](https://nextmail.sh/docs/go/reference/chats#listAll), [`Chats.Iterate`](https://nextmail.sh/docs/go/reference/chats#iterate); Java [`chats().list`](https://nextmail.sh/docs/java/reference/chats#list), [`chats().listAll`](https://nextmail.sh/docs/java/reference/chats#listAll), [`chats().iterate`](https://nextmail.sh/docs/java/reference/chats#iterate); C# [`Chats.ListAsync`](https://nextmail.sh/docs/csharp/reference/chats#list), [`Chats.ListAllAsync`](https://nextmail.sh/docs/csharp/reference/chats#listAll), [`Chats.IterateAsync`](https://nextmail.sh/docs/csharp/reference/chats#iterate); CLI [`nextmail chats list`](https://nextmail.sh/docs/cli/reference/chats#chats-list); MCP [`listChats`](https://nextmail.sh/docs/mcp/tools/chats#listChats). ### `GET /chats/{id}` Retrieve a chat One chat by id. Each person reaches only their own chats: an API key reaches the chats of the workspace owner, and an app reaches the chats of the person who connected it. A key or an app limited to particular addresses or domains is a 422 `capability_unsupported`. Requires the `threads:read` scope. - Scopes: `threads:read`. **Path parameters** - `id` (`string`, required): The chat id from `GET /chats`. **Returns** - `200` `Chat`: The chat. **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.chats.get()`](https://nextmail.sh/docs/sdk/reference/chats#get); Python [`chats.get()`](https://nextmail.sh/docs/python/reference/chats#get); Ruby [`chats.get`](https://nextmail.sh/docs/ruby/reference/chats#get); PHP [`chats->get`](https://nextmail.sh/docs/php/reference/chats#get); Go [`Chats.Get`](https://nextmail.sh/docs/go/reference/chats#get); Java [`chats().get`](https://nextmail.sh/docs/java/reference/chats#get); C# [`Chats.GetAsync`](https://nextmail.sh/docs/csharp/reference/chats#get); CLI [`nextmail chats get`](https://nextmail.sh/docs/cli/reference/chats#chats-get); MCP [`getChat`](https://nextmail.sh/docs/mcp/tools/chats#getChat). ### `PATCH /chats/{id}` Rename a chat Gives the chat a new title. Each person reaches only their own chats: an API key reaches the chats of the workspace owner, and an app reaches the chats of the person who connected it. A key or an app limited to particular addresses or domains is a 422 `capability_unsupported`. Requires the `threads:write` scope. - Scopes: `threads:write`. **Path parameters** - `id` (`string`, required): The chat id from `GET /chats`. **Request body** - `title` (`string`, required, 1 to 120 characters) **Returns** - `200` `Chat`: The chat with its new title. **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.chats.rename()`](https://nextmail.sh/docs/sdk/reference/chats#rename); Python [`chats.rename()`](https://nextmail.sh/docs/python/reference/chats#rename); Ruby [`chats.rename`](https://nextmail.sh/docs/ruby/reference/chats#rename); PHP [`chats->rename`](https://nextmail.sh/docs/php/reference/chats#rename); Go [`Chats.Rename`](https://nextmail.sh/docs/go/reference/chats#rename); Java [`chats().rename`](https://nextmail.sh/docs/java/reference/chats#rename); C# [`Chats.RenameAsync`](https://nextmail.sh/docs/csharp/reference/chats#rename); CLI [`nextmail chats rename`](https://nextmail.sh/docs/cli/reference/chats#chats-rename); MCP [`renameChat`](https://nextmail.sh/docs/mcp/tools/chats#renameChat). ### `DELETE /chats/{id}` Delete a chat Deletes the chat and every message in it, for good. Nothing it did in the mailbox is undone. Each person reaches only their own chats: an API key reaches the chats of the workspace owner, and an app reaches the chats of the person who connected it. A key or an app limited to particular addresses or domains is a 422 `capability_unsupported`. Requires the `threads:write` scope. - Scopes: `threads:write`. **Path parameters** - `id` (`string`, required): The chat id from `GET /chats`. **Returns** - `200` `DeletedChat`: 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.chats.delete()`](https://nextmail.sh/docs/sdk/reference/chats#delete); Python [`chats.delete()`](https://nextmail.sh/docs/python/reference/chats#delete); Ruby [`chats.delete`](https://nextmail.sh/docs/ruby/reference/chats#delete); PHP [`chats->delete`](https://nextmail.sh/docs/php/reference/chats#delete); Go [`Chats.Delete`](https://nextmail.sh/docs/go/reference/chats#delete); Java [`chats().delete`](https://nextmail.sh/docs/java/reference/chats#delete); C# [`Chats.DeleteAsync`](https://nextmail.sh/docs/csharp/reference/chats#delete); CLI [`nextmail chats delete`](https://nextmail.sh/docs/cli/reference/chats#chats-delete); MCP [`deleteChat`](https://nextmail.sh/docs/mcp/tools/chats#deleteChat). ### Objects #### `Chat` `object` - `object` (`string`, required, one of `"chat"`) - `id` (`string`, required) - `title` (`string`, required) - `kind` (`string`, required, one of `"chat"`) - `messageCount` (`integer`, required, at least 0) - `updatedAt` (`string`, required, format `date-time`): When a message last arrived in it. #### `ChatList` `object` - `object` (`string`, one of `"list"`) - `data` (`Chat[]`) - `hasMore` (`boolean`): True when another page follows. Pass `nextCursor` back as `cursor` to read it. - `nextCursor` (`string`, nullable): An opaque cursor for the next page, or null on the last page. Pass it back unchanged. #### `DeletedChat` `object` - `object` (`string`, one of `"chat"`) - `id` (`string`) - `deleted` (`boolean`, one of `true`)