---
title: "Assistant chats"
description: "The conversations held with the assistant in the app."
url: "https://openemail.uk/docs/mcp/tools/chats"
area: "MCP server"
category: "Tools"
---

# Assistant chats

The conversations held with the assistant in the app.

## Assistant chats tools

| Tool | What it does |
| --- | --- |
| listChats | The chats held with the assistant in the app, newest first, with their titles and how many messages each holds. `query` searches the titles. Returned a page at a time. |
| getChat | One chat by its id. |
| renameChat | Give a chat a new title. |
| deleteChat | Delete a chat and every message in it, for good. Nothing the assistant did in the mailbox is undone. |

> Only the workspace owner reaches the chats, through a client connected with every address. Reading needs `threads:read` and changing needs `threads:write`.

> The assistant in the app does not have these tools, so a chat never renames or deletes itself.

## Reference

### `listChats`

The conversations held with the assistant in the OpenEmail app, as its Chats page lists them, newest first, each with its title, id and how many messages it holds. query searches the titles. Only the workspace owner reaches them. One page at a time: when more follow, the last line gives a cursor to pass back for the next page.

- Scopes: `threads:read`.
- MCP only, not in the app's assistant.
- Toolkit: `core`.

**Inputs**

- `query` (`string`, up to 200 characters)
- `sort` (`string`, one of `"newest"`, `"oldest"`, `"title"`)
- `limit` (`integer`, at least 1, at most 100)
- `cursor` (`string`, 1 to 2048 characters)

Also available in: API [`GET /chats`](https://openemail.uk/docs/api/reference/chats#get-chats); SDK [`chats.list()`](https://openemail.uk/docs/sdk/reference/chats#list), [`chats.listAll()`](https://openemail.uk/docs/sdk/reference/chats#listAll), [`chats.iterate()`](https://openemail.uk/docs/sdk/reference/chats#iterate).

### `getChat`

One chat with the assistant by its id: its title, how many messages it holds and when it last changed.

- Scopes: `threads:read`.
- MCP only, not in the app's assistant.
- Toolkit: `core`.

**Inputs**

- `id` (`string`, required, not empty)

Also available in: API [`GET /chats/{id}`](https://openemail.uk/docs/api/reference/chats#get-chats-id); SDK [`chats.get()`](https://openemail.uk/docs/sdk/reference/chats#get).

### `renameChat`

Give a chat with the assistant a new title.

- Scopes: `threads:write`.
- MCP only, not in the app's assistant.
- Toolkit: `core`.

**Inputs**

- `id` (`string`, required, not empty)
- `title` (`string`, required, 1 to 120 characters)

Also available in: API [`PATCH /chats/{id}`](https://openemail.uk/docs/api/reference/chats#patch-chats-id); SDK [`chats.rename()`](https://openemail.uk/docs/sdk/reference/chats#rename).

### `deleteChat`

Delete a chat with the assistant and every message in it, for good. Nothing it did in the mailbox is undone. Ask the person first.

- Scopes: `threads:write`.
- MCP only, not in the app's assistant.
- Toolkit: `core`.

**Inputs**

- `id` (`string`, required, not empty)

Also available in: API [`DELETE /chats/{id}`](https://openemail.uk/docs/api/reference/chats#delete-chats-id); SDK [`chats.delete()`](https://openemail.uk/docs/sdk/reference/chats#delete).