---
title: "Organising"
description: "Labels and read state."
url: "https://nextmail.sh/docs/mcp/tools/organising"
area: "MCP server"
category: "Tools"
---

# Organising

Labels and read state.

## Organising tools

| Tool | What it does |
| --- | --- |
| markThreadsRead | Mark one or more threads read. |
| markThreadsUnread | Mark one or more threads unread. |
| modifyLabels | Add or remove labels on threads, each named by its id or its name. A label that does not exist is refused, not created. |
| getUserLabels | Every label, sorted by name, with its id, its colour and how many conversations carry it, a page at a time. |
| getLabel | One label by id or name, with its colour, its conversation count and when it was created and last changed. |
| createLabel | Create a label, coloured with a hex value or a gradient token. |
| updateLabel | Rename or recolour a label. Its id stays, so every conversation keeps it. |
| deleteLabel | Delete a label and take it off every conversation. There is no undo. |
| trashThreads | Move threads to the Bin, out of the inbox, spam, snoozed and archive at once. Nothing is deleted. |
| restoreThreads | Take threads back out of the Bin or Spam and put them in the inbox. |
| deleteThreadsForever | Delete threads for good, every message and attachment in them. There is no undo. |
| snoozeThreads | Hide threads until `wakeAt`, a future ISO 8601 instant, when they come back to the inbox. |
| unsnoozeThreads | Bring snoozed threads back to the inbox now and cancel their wake time. |
| muteThreads | Mute threads: each leaves the inbox for the archive, and new mail in it arrives archived, unread and silent. |
| unmuteThreads | Take the mute off, so the next message arrives in the inbox again. |
| listFollowUps | The reminders set on mail you sent: waiting, answered, due or cancelled. |
| setFollowUp | Ask to be reminded about a thread if nobody replies by `remindAt`, a future ISO 8601 instant. |
| cancelFollowUp | Cancel a waiting reminder by its id. |
| listSenderCategories | The senders whose mail always goes to one inbox tab. |
| setSenderCategory | Always sort one sender into `primary`, `promotions`, `updates`, `social` or `forums`. |
| clearSenderCategory | Remove a sender’s tab, so the rules sort their mail again. |
| testLabel | Try a label’s AI instructions on recent inbox mail without labelling anything. It spends one AI action. |

> Labelling a conversation with `modifyLabels` needs “Label, read and archive threads” (`threads:write`), as it does in the app. Creating, renaming, recolouring and deleting need “Create and edit labels” (`labels:write`), and someone limited to particular addresses also needs “Change mailbox settings and the signature” (`settings:write`) to rename, recolour or delete, because those change the label for everybody.

> A colour is a hex value such as `#3B82F6` or one of the seven gradient tokens, `gradient:sunset` to `gradient:midnight`. `GET /labels/colors` on the REST API lists the whole palette.

> A label’s id comes from the name it was created with, so `Big Clients` is `USER_BIG_CLIENTS`, and it survives a rename. `createLabel` refuses a name another label already has rather than overwriting that label.

> An MCP client decides for itself whether to ask you before a tool runs. `deleteLabel` cannot be undone, so its description tells the model to check with you first.

> Moving, restoring, snoozing and deleting threads need “Label, read and archive threads” (`threads:write`), and a client limited to some addresses reaches only the threads that arrived at them. In the app’s chat, `deleteThreadsForever` always asks first, and the other four ask unless you asked for them.

> Muting, reminders and sender tabs need “Label, read and archive threads” (`threads:write`) too. A mute applies to everyone on the workspace. `sendEmail` and `replyToEmail` take `followUpAt` to set a reminder as the mail goes out, and `listThreads` takes `category` to read one inbox tab.

> `createLabel` and `updateLabel` take `aiInstructions` and `aiEnabled`: with both, AI applies the label to arriving mail that fits what you wrote. It needs a paid plan, a workspace may have ten such labels, and it only ever adds the label.

## Reference

### `markThreadsRead`

Mark email threads as read

- Scopes: `threads:write`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `core`.

**Inputs**

- `threadIds` (`string[]`, required, up to 1000 items)

Also available in: API [`PATCH /threads/{id}`](https://nextmail.sh/docs/api/reference/threads#patch-threads-id); TypeScript [`nextmail.threads.update()`](https://nextmail.sh/docs/sdk/reference/threads#update); Python [`threads.update()`](https://nextmail.sh/docs/python/reference/threads#update); Ruby [`threads.update`](https://nextmail.sh/docs/ruby/reference/threads#update); PHP [`threads->update`](https://nextmail.sh/docs/php/reference/threads#update); Go [`Threads.Update`](https://nextmail.sh/docs/go/reference/threads#update); Java [`threads().update`](https://nextmail.sh/docs/java/reference/threads#update); C# [`Threads.UpdateAsync`](https://nextmail.sh/docs/csharp/reference/threads#update).

### `markThreadsUnread`

Mark email threads as unread

- Scopes: `threads:write`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `core`.

**Inputs**

- `threadIds` (`string[]`, required, up to 1000 items)

Also available in: API [`PATCH /threads/{id}`](https://nextmail.sh/docs/api/reference/threads#patch-threads-id); TypeScript [`nextmail.threads.update()`](https://nextmail.sh/docs/sdk/reference/threads#update); Python [`threads.update()`](https://nextmail.sh/docs/python/reference/threads#update); Ruby [`threads.update`](https://nextmail.sh/docs/ruby/reference/threads#update); PHP [`threads->update`](https://nextmail.sh/docs/php/reference/threads#update); Go [`Threads.Update`](https://nextmail.sh/docs/go/reference/threads#update); Java [`threads().update`](https://nextmail.sh/docs/java/reference/threads#update); C# [`Threads.UpdateAsync`](https://nextmail.sh/docs/csharp/reference/threads#update).

### `modifyLabels`

Add or remove labels on email threads. Name each label by its id (USER_RECEIPTS) or by its name as getUserLabels lists it. The system labels STARRED, IMPORTANT, UNREAD, INBOX and ARCHIVE are accepted too, so archiving is adding ARCHIVE and removing INBOX. A label that does not exist is refused rather than created: call createLabel first.

- Scopes: `threads:write`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `core`.

**Inputs**

- `threadIds` (`string[]`, required, up to 1000 items)
- `addLabelIds` (`string[]`, required): Labels to put on, by id or by name.
- `removeLabelIds` (`string[]`, required): Labels to take off, by id or by name.

Also available in: API [`PATCH /threads/{id}`](https://nextmail.sh/docs/api/reference/threads#patch-threads-id), [`POST /threads/{id}/restore`](https://nextmail.sh/docs/api/reference/threads#post-threads-id-restore); TypeScript [`nextmail.threads.update()`](https://nextmail.sh/docs/sdk/reference/threads#update), [`nextmail.threads.restore()`](https://nextmail.sh/docs/sdk/reference/threads#restore); Python [`threads.update()`](https://nextmail.sh/docs/python/reference/threads#update), [`threads.restore()`](https://nextmail.sh/docs/python/reference/threads#restore); Ruby [`threads.update`](https://nextmail.sh/docs/ruby/reference/threads#update), [`threads.restore`](https://nextmail.sh/docs/ruby/reference/threads#restore); PHP [`threads->update`](https://nextmail.sh/docs/php/reference/threads#update), [`threads->restore`](https://nextmail.sh/docs/php/reference/threads#restore); Go [`Threads.Update`](https://nextmail.sh/docs/go/reference/threads#update), [`Threads.Restore`](https://nextmail.sh/docs/go/reference/threads#restore); Java [`threads().update`](https://nextmail.sh/docs/java/reference/threads#update), [`threads().restore`](https://nextmail.sh/docs/java/reference/threads#restore); C# [`Threads.UpdateAsync`](https://nextmail.sh/docs/csharp/reference/threads#update), [`Threads.RestoreAsync`](https://nextmail.sh/docs/csharp/reference/threads#restore).

### `getUserLabels`

The labels in this workspace, sorted by name. Each line gives the name, the id that modifyLabels, updateLabel and deleteLabel take, the colour (a hex value or a gradient token such as gradient:sunset) and how many conversations carry the label. An id comes from the name the label was created with and never changes, even after a rename. One page at a time: when more follow, the last line gives a cursor to pass back for the next page.

- Scopes: `labels:read`.
- The app's assistant runs it without asking.
- Toolkit: `core`.

**Inputs**

- `limit` (`integer`, at least 1, at most 100)
- `cursor` (`string`)

Also available in: API [`GET /labels`](https://nextmail.sh/docs/api/reference/labels#get-labels), [`GET /labels/{id}`](https://nextmail.sh/docs/api/reference/labels#get-labels-id); TypeScript [`nextmail.labels.list()`](https://nextmail.sh/docs/sdk/reference/labels#list), [`nextmail.labels.listAll()`](https://nextmail.sh/docs/sdk/reference/labels#listAll), [`nextmail.labels.iterate()`](https://nextmail.sh/docs/sdk/reference/labels#iterate), [`nextmail.labels.get()`](https://nextmail.sh/docs/sdk/reference/labels#get); Python [`labels.list()`](https://nextmail.sh/docs/python/reference/labels#list), [`labels.list_all()`](https://nextmail.sh/docs/python/reference/labels#listAll), [`labels.iterate()`](https://nextmail.sh/docs/python/reference/labels#iterate), [`labels.get()`](https://nextmail.sh/docs/python/reference/labels#get); Ruby [`labels.list`](https://nextmail.sh/docs/ruby/reference/labels#list), [`labels.list_all`](https://nextmail.sh/docs/ruby/reference/labels#listAll), [`labels.iterate`](https://nextmail.sh/docs/ruby/reference/labels#iterate), [`labels.get`](https://nextmail.sh/docs/ruby/reference/labels#get); PHP [`labels->list`](https://nextmail.sh/docs/php/reference/labels#list), [`labels->listAll`](https://nextmail.sh/docs/php/reference/labels#listAll), [`labels->iterate`](https://nextmail.sh/docs/php/reference/labels#iterate), [`labels->get`](https://nextmail.sh/docs/php/reference/labels#get); Go [`Labels.List`](https://nextmail.sh/docs/go/reference/labels#list), [`Labels.ListAll`](https://nextmail.sh/docs/go/reference/labels#listAll), [`Labels.Iterate`](https://nextmail.sh/docs/go/reference/labels#iterate), [`Labels.Get`](https://nextmail.sh/docs/go/reference/labels#get); Java [`labels().list`](https://nextmail.sh/docs/java/reference/labels#list), [`labels().listAll`](https://nextmail.sh/docs/java/reference/labels#listAll), [`labels().iterate`](https://nextmail.sh/docs/java/reference/labels#iterate), [`labels().get`](https://nextmail.sh/docs/java/reference/labels#get); C# [`Labels.ListAsync`](https://nextmail.sh/docs/csharp/reference/labels#list), [`Labels.ListAllAsync`](https://nextmail.sh/docs/csharp/reference/labels#listAll), [`Labels.IterateAsync`](https://nextmail.sh/docs/csharp/reference/labels#iterate), [`Labels.GetAsync`](https://nextmail.sh/docs/csharp/reference/labels#get).

### `getLabel`

One label in detail: its name, id, colour, how many conversations carry it, and when it was created and last changed.

- Scopes: `labels:read`.
- The app's assistant runs it without asking.
- Toolkit: `workspace`.

**Inputs**

- `id` (`string`, required): The label id, or its name.

Also available in: API [`GET /labels`](https://nextmail.sh/docs/api/reference/labels#get-labels), [`GET /labels/{id}`](https://nextmail.sh/docs/api/reference/labels#get-labels-id); TypeScript [`nextmail.labels.list()`](https://nextmail.sh/docs/sdk/reference/labels#list), [`nextmail.labels.listAll()`](https://nextmail.sh/docs/sdk/reference/labels#listAll), [`nextmail.labels.iterate()`](https://nextmail.sh/docs/sdk/reference/labels#iterate), [`nextmail.labels.get()`](https://nextmail.sh/docs/sdk/reference/labels#get); Python [`labels.list()`](https://nextmail.sh/docs/python/reference/labels#list), [`labels.list_all()`](https://nextmail.sh/docs/python/reference/labels#listAll), [`labels.iterate()`](https://nextmail.sh/docs/python/reference/labels#iterate), [`labels.get()`](https://nextmail.sh/docs/python/reference/labels#get); Ruby [`labels.list`](https://nextmail.sh/docs/ruby/reference/labels#list), [`labels.list_all`](https://nextmail.sh/docs/ruby/reference/labels#listAll), [`labels.iterate`](https://nextmail.sh/docs/ruby/reference/labels#iterate), [`labels.get`](https://nextmail.sh/docs/ruby/reference/labels#get); PHP [`labels->list`](https://nextmail.sh/docs/php/reference/labels#list), [`labels->listAll`](https://nextmail.sh/docs/php/reference/labels#listAll), [`labels->iterate`](https://nextmail.sh/docs/php/reference/labels#iterate), [`labels->get`](https://nextmail.sh/docs/php/reference/labels#get); Go [`Labels.List`](https://nextmail.sh/docs/go/reference/labels#list), [`Labels.ListAll`](https://nextmail.sh/docs/go/reference/labels#listAll), [`Labels.Iterate`](https://nextmail.sh/docs/go/reference/labels#iterate), [`Labels.Get`](https://nextmail.sh/docs/go/reference/labels#get); Java [`labels().list`](https://nextmail.sh/docs/java/reference/labels#list), [`labels().listAll`](https://nextmail.sh/docs/java/reference/labels#listAll), [`labels().iterate`](https://nextmail.sh/docs/java/reference/labels#iterate), [`labels().get`](https://nextmail.sh/docs/java/reference/labels#get); C# [`Labels.ListAsync`](https://nextmail.sh/docs/csharp/reference/labels#list), [`Labels.ListAllAsync`](https://nextmail.sh/docs/csharp/reference/labels#listAll), [`Labels.IterateAsync`](https://nextmail.sh/docs/csharp/reference/labels#iterate), [`Labels.GetAsync`](https://nextmail.sh/docs/csharp/reference/labels#get).

### `createLabel`

Create a new email label. A workspace holds at most 50 of them. The id comes from the name (Big Clients becomes USER_BIG_CLIENTS), so a name another label already has, or whose id another label holds, is refused. Leave backgroundColor out for a label with no colour. A label colour is a hex colour such as #3B82F6, or one of the gradient tokens gradient:sunset, gradient:ember, gradient:meadow, gradient:lagoon, gradient:aurora, gradient:berry, gradient:midnight. The app offers #EF4444, #F97316, #EA9602, #DCB30B, #79BB19, #2EB45C, #00AD9B, #09A9CA, #3B82F6, #6366F1, #8B5CF6, #D946EF, #EC4899, #64748B as its solid swatches, and any other hex is kept as it is. With aiInstructions and aiEnabled, AI applies the label to arriving mail that fits what you wrote, and testLabel tries it on recent mail first.

- Scopes: `labels:write`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `core`.

**Inputs**

- `name` (`string`, required, not empty)
- `backgroundColor` (`string`): A label colour is a hex colour such as #3B82F6, or one of the gradient tokens gradient:sunset, gradient:ember, gradient:meadow, gradient:lagoon, gradient:aurora, gradient:berry, gradient:midnight. The app offers #EF4444, #F97316, #EA9602, #DCB30B, #79BB19, #2EB45C, #00AD9B, #09A9CA, #3B82F6, #6366F1, #8B5CF6, #D946EF, #EC4899, #64748B as its solid swatches, and any other hex is kept as it is.
- `aiInstructions` (`string`, up to 500 characters): What the label is for, in plain words, such as "invoices and receipts" or "anything from investors". With aiEnabled on, AI reads each arriving message against it and adds the label when it fits. An empty string clears it.
- `aiEnabled` (`boolean`): true has AI apply the label to arriving mail that fits aiInstructions. It only ever adds the label and never archives or moves mail. It needs instructions and a paid plan, and a workspace may have ten such labels.

Also available in: API [`POST /labels`](https://nextmail.sh/docs/api/reference/labels#post-labels); TypeScript [`nextmail.labels.create()`](https://nextmail.sh/docs/sdk/reference/labels#create); Python [`labels.create()`](https://nextmail.sh/docs/python/reference/labels#create); Ruby [`labels.create`](https://nextmail.sh/docs/ruby/reference/labels#create); PHP [`labels->create`](https://nextmail.sh/docs/php/reference/labels#create); Go [`Labels.Create`](https://nextmail.sh/docs/go/reference/labels#create); Java [`labels().create`](https://nextmail.sh/docs/java/reference/labels#create); C# [`Labels.CreateAsync`](https://nextmail.sh/docs/csharp/reference/labels#create).

### `updateLabel`

Rename or recolour a label, or change what AI does with it. Name it by its id or its current name, and give any of name, backgroundColor, aiInstructions and aiEnabled: a field left out stays as it is, and an empty backgroundColor clears the colour. The id never changes, so every conversation keeps the label through a rename. A label colour is a hex colour such as #3B82F6, or one of the gradient tokens gradient:sunset, gradient:ember, gradient:meadow, gradient:lagoon, gradient:aurora, gradient:berry, gradient:midnight. The app offers #EF4444, #F97316, #EA9602, #DCB30B, #79BB19, #2EB45C, #00AD9B, #09A9CA, #3B82F6, #6366F1, #8B5CF6, #D946EF, #EC4899, #64748B as its solid swatches, and any other hex is kept as it is.

- Scopes: `labels:write`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `core`.

**Inputs**

- `id` (`string`, required, not empty): The label id, or its current name.
- `name` (`string`, not empty): The new name.
- `backgroundColor` (`string`): The new colour. An empty string clears it.
- `aiInstructions` (`string`, up to 500 characters): What the label is for, in plain words, such as "invoices and receipts" or "anything from investors". With aiEnabled on, AI reads each arriving message against it and adds the label when it fits. An empty string clears it.
- `aiEnabled` (`boolean`): true has AI apply the label to arriving mail that fits aiInstructions. It only ever adds the label and never archives or moves mail. It needs instructions and a paid plan, and a workspace may have ten such labels.

Also available in: API [`PATCH /labels/{id}`](https://nextmail.sh/docs/api/reference/labels#patch-labels-id); TypeScript [`nextmail.labels.update()`](https://nextmail.sh/docs/sdk/reference/labels#update); Python [`labels.update()`](https://nextmail.sh/docs/python/reference/labels#update); Ruby [`labels.update`](https://nextmail.sh/docs/ruby/reference/labels#update); PHP [`labels->update`](https://nextmail.sh/docs/php/reference/labels#update); Go [`Labels.Update`](https://nextmail.sh/docs/go/reference/labels#update); Java [`labels().update`](https://nextmail.sh/docs/java/reference/labels#update); C# [`Labels.UpdateAsync`](https://nextmail.sh/docs/csharp/reference/labels#update).

### `deleteLabel`

Delete a label for good and take it off every conversation that carries it. The conversations stay where they are. There is no undo: creating the same name again gives the same id, but the conversations do not get the label back. Name the label by its id or its name, and check with the person you are working for first.

- Scopes: `labels:write`.
- The app's assistant always asks first.
- Toolkit: `core`.

**Inputs**

- `id` (`string`, required, not empty): The label id, or its name.

Also available in: API [`DELETE /labels/{id}`](https://nextmail.sh/docs/api/reference/labels#delete-labels-id); TypeScript [`nextmail.labels.delete()`](https://nextmail.sh/docs/sdk/reference/labels#delete); Python [`labels.delete()`](https://nextmail.sh/docs/python/reference/labels#delete); Ruby [`labels.delete`](https://nextmail.sh/docs/ruby/reference/labels#delete); PHP [`labels->delete`](https://nextmail.sh/docs/php/reference/labels#delete); Go [`Labels.Delete`](https://nextmail.sh/docs/go/reference/labels#delete); Java [`labels().delete`](https://nextmail.sh/docs/java/reference/labels#delete); C# [`Labels.DeleteAsync`](https://nextmail.sh/docs/csharp/reference/labels#delete).

### `trashThreads`

Move email threads to the Bin, as the delete button of the app does: each one leaves the inbox, spam, snoozed and archive at once, and a snoozed one no longer wakes. Nothing is deleted, and restoreThreads takes them back out.

- Scopes: `threads:write`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `core`.

**Inputs**

- `threadIds` (`string[]`, required, 1 to 1000 items)

Also available in: API [`POST /threads/{id}/trash`](https://nextmail.sh/docs/api/reference/threads#post-threads-id-trash); TypeScript [`nextmail.threads.trash()`](https://nextmail.sh/docs/sdk/reference/threads#trash); Python [`threads.trash()`](https://nextmail.sh/docs/python/reference/threads#trash); Ruby [`threads.trash`](https://nextmail.sh/docs/ruby/reference/threads#trash); PHP [`threads->trash`](https://nextmail.sh/docs/php/reference/threads#trash); Go [`Threads.Trash`](https://nextmail.sh/docs/go/reference/threads#trash); Java [`threads().trash`](https://nextmail.sh/docs/java/reference/threads#trash); C# [`Threads.TrashAsync`](https://nextmail.sh/docs/csharp/reference/threads#trash).

### `restoreThreads`

Take email threads out of the Bin or Spam and put them back in the inbox, as Restore from Bin does. A thread that is already in the inbox stays there.

- Scopes: `threads:write`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `core`.

**Inputs**

- `threadIds` (`string[]`, required, 1 to 1000 items)

Also available in: API [`PATCH /threads/{id}`](https://nextmail.sh/docs/api/reference/threads#patch-threads-id), [`POST /threads/{id}/restore`](https://nextmail.sh/docs/api/reference/threads#post-threads-id-restore); TypeScript [`nextmail.threads.update()`](https://nextmail.sh/docs/sdk/reference/threads#update), [`nextmail.threads.restore()`](https://nextmail.sh/docs/sdk/reference/threads#restore); Python [`threads.update()`](https://nextmail.sh/docs/python/reference/threads#update), [`threads.restore()`](https://nextmail.sh/docs/python/reference/threads#restore); Ruby [`threads.update`](https://nextmail.sh/docs/ruby/reference/threads#update), [`threads.restore`](https://nextmail.sh/docs/ruby/reference/threads#restore); PHP [`threads->update`](https://nextmail.sh/docs/php/reference/threads#update), [`threads->restore`](https://nextmail.sh/docs/php/reference/threads#restore); Go [`Threads.Update`](https://nextmail.sh/docs/go/reference/threads#update), [`Threads.Restore`](https://nextmail.sh/docs/go/reference/threads#restore); Java [`threads().update`](https://nextmail.sh/docs/java/reference/threads#update), [`threads().restore`](https://nextmail.sh/docs/java/reference/threads#restore); C# [`Threads.UpdateAsync`](https://nextmail.sh/docs/csharp/reference/threads#update), [`Threads.RestoreAsync`](https://nextmail.sh/docs/csharp/reference/threads#restore).

### `deleteThreadsForever`

Delete email threads for good, every message and attachment in them, as Delete from Bin does in the app. This cannot be undone. To throw mail away without losing it, use trashThreads instead.

- Scopes: `threads:write`.
- The app's assistant always asks first.
- Toolkit: `core`.

**Inputs**

- `threadIds` (`string[]`, required, 1 to 1000 items)

Also available in: API [`DELETE /threads/{id}`](https://nextmail.sh/docs/api/reference/threads#delete-threads-id); TypeScript [`nextmail.threads.delete()`](https://nextmail.sh/docs/sdk/reference/threads#delete); Python [`threads.delete()`](https://nextmail.sh/docs/python/reference/threads#delete); Ruby [`threads.delete`](https://nextmail.sh/docs/ruby/reference/threads#delete); PHP [`threads->delete`](https://nextmail.sh/docs/php/reference/threads#delete); Go [`Threads.Delete`](https://nextmail.sh/docs/go/reference/threads#delete); Java [`threads().delete`](https://nextmail.sh/docs/java/reference/threads#delete); C# [`Threads.DeleteAsync`](https://nextmail.sh/docs/csharp/reference/threads#delete).

### `snoozeThreads`

Hide email threads until a set time, as Snooze does: each leaves the inbox and comes back to it at wakeAt, an ISO 8601 instant in the future such as 2026-10-05T09:00:00Z. Threads wake at an hourly sweep, so up to an hour late. Snoozing a snoozed thread again replaces its wake time. getCurrentDate gives the time now.

- Scopes: `threads:write`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `core`.

**Inputs**

- `threadIds` (`string[]`, required, 1 to 1000 items)
- `wakeAt` (`string`, required, format `date-time`)

Also available in: API [`POST /threads/{id}/snooze`](https://nextmail.sh/docs/api/reference/threads#post-threads-id-snooze); TypeScript [`nextmail.threads.snooze()`](https://nextmail.sh/docs/sdk/reference/threads#snooze); Python [`threads.snooze()`](https://nextmail.sh/docs/python/reference/threads#snooze); Ruby [`threads.snooze`](https://nextmail.sh/docs/ruby/reference/threads#snooze); PHP [`threads->snooze`](https://nextmail.sh/docs/php/reference/threads#snooze); Go [`Threads.Snooze`](https://nextmail.sh/docs/go/reference/threads#snooze); Java [`threads().snooze`](https://nextmail.sh/docs/java/reference/threads#snooze); C# [`Threads.SnoozeAsync`](https://nextmail.sh/docs/csharp/reference/threads#snooze).

### `unsnoozeThreads`

Bring snoozed email threads back to the inbox now and cancel their wake time. A thread that is not snoozed is left as it is and reported.

- Scopes: `threads:write`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `core`.

**Inputs**

- `threadIds` (`string[]`, required, 1 to 1000 items)

Also available in: API [`POST /threads/{id}/unsnooze`](https://nextmail.sh/docs/api/reference/threads#post-threads-id-unsnooze); TypeScript [`nextmail.threads.unsnooze()`](https://nextmail.sh/docs/sdk/reference/threads#unsnooze); Python [`threads.unsnooze()`](https://nextmail.sh/docs/python/reference/threads#unsnooze); Ruby [`threads.unsnooze`](https://nextmail.sh/docs/ruby/reference/threads#unsnooze); PHP [`threads->unsnooze`](https://nextmail.sh/docs/php/reference/threads#unsnooze); Go [`Threads.Unsnooze`](https://nextmail.sh/docs/go/reference/threads#unsnooze); Java [`threads().unsnooze`](https://nextmail.sh/docs/java/reference/threads#unsnooze); C# [`Threads.UnsnoozeAsync`](https://nextmail.sh/docs/csharp/reference/threads#unsnooze).

### `muteThreads`

Mute email threads, as Mute does: a thread in the inbox moves to the archive, and from then on new mail in it goes straight to the archive, unread, with no push, sound or desktop notice. It mutes the thread for everyone on the workspace, and mail addressed only to one person does not bring it back. unmuteThreads undoes it.

- Scopes: `threads:write`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `core`.

**Inputs**

- `threadIds` (`string[]`, required, 1 to 1000 items)

Also available in: API [`POST /threads/{id}/mute`](https://nextmail.sh/docs/api/reference/threads#post-threads-id-mute); TypeScript [`nextmail.threads.mute()`](https://nextmail.sh/docs/sdk/reference/threads#mute); Python [`threads.mute()`](https://nextmail.sh/docs/python/reference/threads#mute); Ruby [`threads.mute`](https://nextmail.sh/docs/ruby/reference/threads#mute); PHP [`threads->mute`](https://nextmail.sh/docs/php/reference/threads#mute); Go [`Threads.Mute`](https://nextmail.sh/docs/go/reference/threads#mute); Java [`threads().mute`](https://nextmail.sh/docs/java/reference/threads#mute); C# [`Threads.MuteAsync`](https://nextmail.sh/docs/csharp/reference/threads#mute).

### `unmuteThreads`

Take the mute off email threads, so the next message in each arrives in the inbox and alerts people again. The threads stay where they are: move one back to the inbox with modifyLabels if it should be there now. A thread that is not muted is left as it is.

- Scopes: `threads:write`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `core`.

**Inputs**

- `threadIds` (`string[]`, required, 1 to 1000 items)

Also available in: API [`POST /threads/{id}/unmute`](https://nextmail.sh/docs/api/reference/threads#post-threads-id-unmute); TypeScript [`nextmail.threads.unmute()`](https://nextmail.sh/docs/sdk/reference/threads#unmute); Python [`threads.unmute()`](https://nextmail.sh/docs/python/reference/threads#unmute); Ruby [`threads.unmute`](https://nextmail.sh/docs/ruby/reference/threads#unmute); PHP [`threads->unmute`](https://nextmail.sh/docs/php/reference/threads#unmute); Go [`Threads.Unmute`](https://nextmail.sh/docs/go/reference/threads#unmute); Java [`threads().unmute`](https://nextmail.sh/docs/java/reference/threads#unmute); C# [`Threads.UnmuteAsync`](https://nextmail.sh/docs/csharp/reference/threads#unmute).

### `listFollowUps`

The reminders set on mail you sent, newest first: waiting for a reply, answered, due (the time came with no reply and the thread is back in the inbox) or cancelled. status keeps one state and threadId the reminders of one thread.

- Scopes: `threads:read`.
- The app's assistant runs it without asking.
- Toolkit: `core`.

**Inputs**

- `status` (`string`, one of `"waiting"`, `"answered"`, `"due"`, `"cancelled"`)
- `threadId` (`string`, 1 to 256 characters)
- `limit` (`integer`, at least 1, at most 200)

Also available in: API [`GET /follow-ups`](https://nextmail.sh/docs/api/reference/threads#get-follow-ups); TypeScript [`nextmail.followUps.list()`](https://nextmail.sh/docs/sdk/reference/follow-ups#list); Python [`follow_ups.list()`](https://nextmail.sh/docs/python/reference/follow-ups#list); Ruby [`follow_ups.list`](https://nextmail.sh/docs/ruby/reference/follow-ups#list); PHP [`followUps->list`](https://nextmail.sh/docs/php/reference/follow-ups#list); Go [`FollowUps.List`](https://nextmail.sh/docs/go/reference/follow-ups#list); Java [`followUps().list`](https://nextmail.sh/docs/java/reference/follow-ups#list); C# [`FollowUps.ListAsync`](https://nextmail.sh/docs/csharp/reference/follow-ups#list).

### `setFollowUp`

Ask to be reminded about a thread if nobody replies by remindAt, an ISO 8601 time in the future, at most a year ahead. If a real reply arrives first the reminder closes by itself. Otherwise the thread returns to the top of the inbox, unread, with a push. Automatic replies, delivery reports and your own sending address do not count as a reply. A thread holds one waiting reminder per person, so setting another moves the time. To set one while sending, pass followUpAt to sendEmail or replyToEmail. getCurrentDate gives the time now.

- Scopes: `threads:write`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `core`.

**Inputs**

- `threadId` (`string`, required, 1 to 256 characters)
- `remindAt` (`string`, required, format `date-time`)

Also available in: API [`POST /follow-ups`](https://nextmail.sh/docs/api/reference/threads#post-follow-ups); TypeScript [`nextmail.followUps.set()`](https://nextmail.sh/docs/sdk/reference/follow-ups#set); Python [`follow_ups.set()`](https://nextmail.sh/docs/python/reference/follow-ups#set); Ruby [`follow_ups.set`](https://nextmail.sh/docs/ruby/reference/follow-ups#set); PHP [`followUps->set`](https://nextmail.sh/docs/php/reference/follow-ups#set); Go [`FollowUps.Set`](https://nextmail.sh/docs/go/reference/follow-ups#set); Java [`followUps().set`](https://nextmail.sh/docs/java/reference/follow-ups#set); C# [`FollowUps.SetAsync`](https://nextmail.sh/docs/csharp/reference/follow-ups#set).

### `cancelFollowUp`

Cancel a waiting reminder by its id from listFollowUps, so the thread stays where it is when the time comes. A reminder that already ended is reported as it is.

- Scopes: `threads:write`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `core`.

**Inputs**

- `id` (`string`, required, 1 to 128 characters)

Also available in: API [`DELETE /follow-ups/{id}`](https://nextmail.sh/docs/api/reference/threads#delete-follow-ups-id); TypeScript [`nextmail.followUps.cancel()`](https://nextmail.sh/docs/sdk/reference/follow-ups#cancel); Python [`follow_ups.cancel()`](https://nextmail.sh/docs/python/reference/follow-ups#cancel); Ruby [`follow_ups.cancel`](https://nextmail.sh/docs/ruby/reference/follow-ups#cancel); PHP [`followUps->cancel`](https://nextmail.sh/docs/php/reference/follow-ups#cancel); Go [`FollowUps.Cancel`](https://nextmail.sh/docs/go/reference/follow-ups#cancel); Java [`followUps().cancel`](https://nextmail.sh/docs/java/reference/follow-ups#cancel); C# [`FollowUps.CancelAsync`](https://nextmail.sh/docs/csharp/reference/follow-ups#cancel).

### `listSenderCategories`

The senders whose mail always goes to one inbox tab. New mail is sorted into primary, promotions, updates, social or forums by plain rules, and a choice listed here wins over them.

- Scopes: `threads:read`.
- The app's assistant runs it without asking.
- Toolkit: `core`.

**Inputs**

Takes no input.

Also available in: API [`GET /sender-categories`](https://nextmail.sh/docs/api/reference/threads#get-sender-categories); TypeScript [`nextmail.threads.listSenderCategories()`](https://nextmail.sh/docs/sdk/reference/threads#listSenderCategories); Python [`threads.list_sender_categories()`](https://nextmail.sh/docs/python/reference/threads#listSenderCategories); Ruby [`threads.list_sender_categories`](https://nextmail.sh/docs/ruby/reference/threads#listSenderCategories); PHP [`threads->listSenderCategories`](https://nextmail.sh/docs/php/reference/threads#listSenderCategories); Go [`Threads.ListSenderCategories`](https://nextmail.sh/docs/go/reference/threads#listSenderCategories); Java [`threads().listSenderCategories`](https://nextmail.sh/docs/java/reference/threads#listSenderCategories); C# [`Threads.ListSenderCategoriesAsync`](https://nextmail.sh/docs/csharp/reference/threads#listSenderCategories).

### `setSenderCategory`

Always sort mail from one sender into one inbox tab: primary, promotions, updates, social or forums. It also moves the inbox threads whose newest message is from them into that tab. Saving again replaces the choice.

- Scopes: `threads:write`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `core`.

**Inputs**

- `sender` (`string`, required, 3 to 320 characters)
- `category` (`string`, required, one of `"primary"`, `"promotions"`, `"updates"`, `"social"`, `"forums"`)

Also available in: API [`PUT /sender-categories/{email}`](https://nextmail.sh/docs/api/reference/threads#put-sender-categories-email); TypeScript [`nextmail.threads.setSenderCategory()`](https://nextmail.sh/docs/sdk/reference/threads#setSenderCategory); Python [`threads.set_sender_category()`](https://nextmail.sh/docs/python/reference/threads#setSenderCategory); Ruby [`threads.set_sender_category`](https://nextmail.sh/docs/ruby/reference/threads#setSenderCategory); PHP [`threads->setSenderCategory`](https://nextmail.sh/docs/php/reference/threads#setSenderCategory); Go [`Threads.SetSenderCategory`](https://nextmail.sh/docs/go/reference/threads#setSenderCategory); Java [`threads().setSenderCategory`](https://nextmail.sh/docs/java/reference/threads#setSenderCategory); C# [`Threads.SetSenderCategoryAsync`](https://nextmail.sh/docs/csharp/reference/threads#setSenderCategory).

### `clearSenderCategory`

Remove the tab choice of one sender, so new mail from them is sorted by the rules again. Threads already sorted stay where they are.

- Scopes: `threads:write`.
- The app's assistant asks first unless you asked for it.
- Toolkit: `core`.

**Inputs**

- `sender` (`string`, required, 3 to 320 characters)

Also available in: API [`DELETE /sender-categories/{email}`](https://nextmail.sh/docs/api/reference/threads#delete-sender-categories-email); TypeScript [`nextmail.threads.clearSenderCategory()`](https://nextmail.sh/docs/sdk/reference/threads#clearSenderCategory); Python [`threads.clear_sender_category()`](https://nextmail.sh/docs/python/reference/threads#clearSenderCategory); Ruby [`threads.clear_sender_category`](https://nextmail.sh/docs/ruby/reference/threads#clearSenderCategory); PHP [`threads->clearSenderCategory`](https://nextmail.sh/docs/php/reference/threads#clearSenderCategory); Go [`Threads.ClearSenderCategory`](https://nextmail.sh/docs/go/reference/threads#clearSenderCategory); Java [`threads().clearSenderCategory`](https://nextmail.sh/docs/java/reference/threads#clearSenderCategory); C# [`Threads.ClearSenderCategoryAsync`](https://nextmail.sh/docs/csharp/reference/threads#clearSenderCategory).

### `testLabel`

Try a label on recent mail: runs the AI over the newest inbox threads and says which ones the label would catch, without labelling anything. Pass aiInstructions to try wording that is not saved yet, or leave it out to try what the label holds. It spends one AI action, which the labelling of arriving mail never does.

- Scopes: `labels:write`, `threads:read`.
- The app's assistant runs it without asking.
- Toolkit: `core`.

**Inputs**

- `id` (`string`, required, not empty): The label id, as getUserLabels lists it.
- `aiInstructions` (`string`, 1 to 500 characters)

Also available in: API [`POST /labels/{id}/test`](https://nextmail.sh/docs/api/reference/labels#post-labels-id-test); TypeScript [`nextmail.labels.test()`](https://nextmail.sh/docs/sdk/reference/labels#test); Python [`labels.test()`](https://nextmail.sh/docs/python/reference/labels#test); Ruby [`labels.test`](https://nextmail.sh/docs/ruby/reference/labels#test); PHP [`labels->test`](https://nextmail.sh/docs/php/reference/labels#test); Go [`Labels.Test`](https://nextmail.sh/docs/go/reference/labels#test); Java [`labels().test`](https://nextmail.sh/docs/java/reference/labels#test); C# [`Labels.TestAsync`](https://nextmail.sh/docs/csharp/reference/labels#test).