---
title: "List labels"
description: "Every label in the workspace, sorted by name, with its colour and how many conversations carry it, a page at a time."
url: "https://nextmail.sh/docs/api/labels/list"
area: "API"
category: "Mailbox"
---

# List labels

Every label in the workspace, sorted by name, with its colour and how many conversations carry it, a page at a time.

`GET /labels`

## GET /labels

Every label in the workspace, sorted by name, with its colour and how many conversations carry it, a page at a time.

## Label ids

**shell**

```
export OE=https://api.nextmail.sh
export AUTH="Authorization: Bearer $NEXTMAIL_API_KEY"
```

A label’s id comes from the name it was created with: `USER_` and the name upper-cased, with each run of spaces turned into `_`, so `Big Clients` is `USER_BIG_CLIENTS`. It never changes, so a renamed label keeps the id of its first name. Store the id rather than the name, and read it from a response rather than building it.

## Example

Needs `labels:read`. Takes `limit` (1 to 100, 25 by default) and `cursor`, and answers with `hasMore` and `nextCursor`: follow `nextCursor` while `hasMore` is true to read every label.

**curl**

```
curl "$OE/labels?limit=2" -H "$AUTH"
```

**Response**

```
{
  "object": "list",
  "data": [
    {
      "object": "label",
      "id": "USER_BIG_CLIENTS",
      "name": "Big Clients",
      "type": "user",
      "color": { "backgroundColor": "gradient:aurora", "textColor": "#18181B" },
      "threadCount": 42,
      "aiInstructions": null,
      "aiEnabled": false,
      "createdAt": "2026-09-22T08:14:03.117Z",
      "updatedAt": "2026-09-22T08:14:03.117Z"
    },
    {
      "object": "label",
      "id": "USER_INVOICES",
      "name": "Invoices",
      "type": "user",
      "color": { "backgroundColor": "#EA9602", "textColor": "#18181B" },
      "threadCount": 318,
      "aiInstructions": "invoices and receipts",
      "aiEnabled": true,
      "createdAt": null,
      "updatedAt": null
    }
  ],
  "hasMore": true,
  "nextCursor": "WyJJbnZvaWNlcyIsIlVTRVJfSU5WT0lDRVMiXQ"
}
```

> System labels such as `INBOX`, `STARRED` and `UNREAD` are not listed. A thread carries them and `PATCH /threads/{id}` takes them, but they cannot be renamed, recoloured or deleted.

> `threadCount` is the number the Labels table in the app shows. For a key limited to particular addresses it counts only conversations delivered to them, while the labels themselves belong to the workspace, so every key sees all of them.

> `color.textColor` is the ink the app draws on the colour, worked out here rather than stored. `createdAt` and `updatedAt` are null on a label made before these times were recorded. `nextCursor` is opaque, so pass it back as it came: it holds the name and id the last row sorts by, so a label renamed or deleted between pages never breaks the walk, and a value this list did not hand out is a 400 `invalid_cursor`.

## Reference

- [`GET /labels`](https://nextmail.sh/docs/api/reference/labels#get-labels): full reference