---
title: "Labels"
description: "Name a label, pick a colour, and filter the list down to it."
url: "https://nextmail.sh/docs/knowledge/reading/labels"
area: "Knowledge base"
category: "Reading & organising"
status: "live"
---

# Labels

Name a label, pick a colour, and filter the list down to it.

## Details

- Created from the + beside Labels in the sidebar or from Settings → Labels. A label is renamed, recoloured or deleted from its menu in the sidebar (the dots, or a right-click) or from its row in Settings → Labels. The sidebar menu is hidden on a label that has children, so a parent is changed from Settings → Labels. Changing or deleting a label needs a role that may edit labels and change mailbox settings, because it changes the label for everybody.
- Clicking a label in the sidebar filters the list you are already in rather than opening a folder of its own, and the ids ride in the URL as ?labels=one,two. A slash in the name nests: Work/Clients shows as Clients under a Work group, and a name in [brackets] is filed under Other. Drag a label by its grip to reorder the sidebar; the order is yours alone, kept per person and per workspace.
- A conversation gets a label three ways: its right-click menu has a Labels submenu that ticks labels on and off, you can drag selected conversations onto a label in the sidebar, and the bar that appears when several are selected applies one to all of them. The submenu offers to create a label only while you have none, so everything else is made on purpose.
- Fourteen colours, ordered around the wheel from red through to pink with a slate at the end, and seven gradients beside them: Sunset, Ember, Meadow, Lagoon, Aurora, Berry and Midnight. Each swatch carries whichever ink reads better on it, near-black or white, so a chip holds its contrast on a light list and does not become a hole in a dark one. The six retired colours and the no-colour default are re-mapped to the nearest new swatch, and any other colour set through the API is kept as it is and offered back as its own swatch when you edit that label.
- Every label has an id, and it comes from the name it was created with: Big Clients is USER_BIG_CLIENTS. The id never changes, so a rename keeps every conversation labelled. Two labels cannot share a name, compared without case, and a new label cannot take the id a renamed one still holds.
- Settings → Labels lists every label with its colour, how many conversations carry it and when it was created and last changed. Deleting a label takes it off every conversation and cannot be undone, so one on ten or more conversations asks you to confirm first.
- Labels belong to the workspace, so every member sees the same set and a rename or a delete changes it for all of them. Switch workspace in the sidebar and the whole set changes. Settings → Labels names the one you are editing, because otherwise the switch looks like the labels have been deleted.
- Everything here works outside the app too. GET /labels pages through the labels with their colours and counts, GET /labels/colors lists the palette, PATCH /threads/{id} puts labels on a conversation and takes them off, and GET /threads?folder=USER_BIG_CLIENTS lists a label’s conversations. The SDK wraps the same calls as nextmail.labels, and the MCP server and the assistant can list, create, rename, recolour, apply and delete labels.