List labels
Every label in the workspace, sorted by name, with its colour and how many conversations carry it, a page at a time.
Runs the real call on your workspace.
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
export OE=https://api.nextmail.shexport 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 "$OE/labels?limit=2" -H "$AUTH"{ "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.
Google Workspace
Fastmail