--- title: "Notes" 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/notes" area: "API" category: "Reference" --- # Notes Every operation in this group: what it accepts, what it returns and the errors it can answer with. ## Operations Private notes pinned to a thread, the Notes panel of the reading pane. Notes are private to a person. A key reads and writes the notes of the workspace owner, and an app those of the person who connected it. A key or an app limited to particular addresses reaches only the notes on threads that arrived at them. ### `GET /threads/{id}/notes` List the notes on a thread Pinned notes first, then the rest in the order they were arranged. Notes are private to a person. A key reads and writes the notes of the workspace owner, and an app those of the person who connected it. Requires the `threads:read` scope. - Scopes: `threads:read`. **Path parameters** - `id` (`string`, required): The thread the notes are on, as `GET /threads` returns it. **Returns** - `200` `ThreadNoteList`: Every note on the thread, in display order. **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 [`threads.listNotes()`](https://openemail.uk/docs/sdk/reference/threads#listNotes); CLI [`openemail threads list-notes`](https://openemail.uk/docs/cli/reference/threads#threads-list-notes); MCP [`listThreadNotes`](https://openemail.uk/docs/mcp/tools/notes#listThreadNotes). ### `POST /threads/{id}/notes` Add a note to a thread A new note goes after the others. `color` is one of the eight the app offers, and `pinned` keeps it at the top. Notes are private to a person. A key reads and writes the notes of the workspace owner, and an app those of the person who connected it. Requires the `threads:write` scope. - Scopes: `threads:write`. **Path parameters** - `id` (`string`, required): The thread the notes are on, as `GET /threads` returns it. **Request body** - `content` (`string`, required, 1 to 20000 characters): The text of the note, up to 20,000 characters. Leading and trailing spaces are trimmed. - `color` (`string`, one of `"default"`, `"red"`, `"orange"`, `"yellow"`, `"green"`, `"blue"`, `"purple"`, `"pink"`): One of the eight the app offers: `default`, `red`, `orange`, `yellow`, `green`, `blue`, `purple` or `pink`. Defaults to `default`. - `pinned` (`boolean`): Keeps the note above the others. Defaults to false. **Returns** - `201` `ThreadNote`: The note. **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 [`threads.createNote()`](https://openemail.uk/docs/sdk/reference/threads#createNote); CLI [`openemail threads create-note`](https://openemail.uk/docs/cli/reference/threads#threads-create-note); MCP [`addThreadNote`](https://openemail.uk/docs/mcp/tools/notes#addThreadNote). ### `POST /threads/{id}/notes/reorder` Arrange the notes on a thread Sets the order of every note on the thread at once, first to last. Pinned notes still come first. `ids` has to name each note exactly once, or the call is a 422 `invalid_parameter` on `ids` and nothing moves. Requires the `threads:write` scope. - Scopes: `threads:write`. **Path parameters** - `id` (`string`, required): The thread the notes are on, as `GET /threads` returns it. **Request body** - `ids` (`string[]`, required, 1 to 200 items) **Returns** - `200` `ThreadNoteList`: The notes, in their new order. **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 [`threads.reorderNotes()`](https://openemail.uk/docs/sdk/reference/threads#reorderNotes); CLI [`openemail threads reorder-notes`](https://openemail.uk/docs/cli/reference/threads#threads-reorder-notes); MCP [`reorderThreadNotes`](https://openemail.uk/docs/mcp/tools/notes#reorderThreadNotes). ### `PATCH /threads/{id}/notes/{noteId}` Change a note Changes its text, its colour or whether it is pinned. Give at least one. A note id that is not on this thread is a 404. Requires the `threads:write` scope. - Scopes: `threads:write`. **Path parameters** - `id` (`string`, required): The thread the notes are on, as `GET /threads` returns it. - `noteId` (`string`, required): The id of a note on that thread. **Request body** - `content` (`string`, 1 to 20000 characters): The new text, up to 20,000 characters. - `color` (`string`, one of `"default"`, `"red"`, `"orange"`, `"yellow"`, `"green"`, `"blue"`, `"purple"`, `"pink"`): The new colour. - `pinned` (`boolean`): Pins or unpins it. **Returns** - `200` `ThreadNote`: The note as it is now. **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 [`threads.updateNote()`](https://openemail.uk/docs/sdk/reference/threads#updateNote); CLI [`openemail threads update-note`](https://openemail.uk/docs/cli/reference/threads#threads-update-note); MCP [`updateThreadNote`](https://openemail.uk/docs/mcp/tools/notes#updateThreadNote). ### `DELETE /threads/{id}/notes/{noteId}` Delete a note Gone for good. There is no bin for notes. Requires the `threads:write` scope. - Scopes: `threads:write`. **Path parameters** - `id` (`string`, required): The thread the notes are on, as `GET /threads` returns it. - `noteId` (`string`, required): The id of a note on that thread. **Returns** - `200` `DeletedThreadNote`: 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 [`threads.deleteNote()`](https://openemail.uk/docs/sdk/reference/threads#deleteNote); CLI [`openemail threads delete-note`](https://openemail.uk/docs/cli/reference/threads#threads-delete-note); MCP [`deleteThreadNote`](https://openemail.uk/docs/mcp/tools/notes#deleteThreadNote). ### Objects #### `DeletedThreadNote` `object` - `object` (`string`, one of `"note"`) - `id` (`string`) - `threadId` (`string`) - `deleted` (`boolean`, one of `true`) #### `ThreadNote` `object` - `object` (`string`, required, one of `"note"`) - `id` (`string`, required) - `threadId` (`string`, required) - `content` (`string`, required, up to 20000 characters) - `color` (`string`, required, one of `"default"`, `"red"`, `"orange"`, `"yellow"`, `"green"`, `"blue"`, `"purple"`, `"pink"`) - `pinned` (`boolean`, required): Pinned notes are listed before the others. - `order` (`integer`, required): Where it sits among the notes that share its pinned state, lowest first. - `createdAt` (`string`, required, format `date-time`) - `updatedAt` (`string`, required, format `date-time`) #### `ThreadNoteList` `object` - `object` (`string`, one of `"list"`) - `data` (`ThreadNote[]`)