---
title: "List labels"
method: GET
path: "/v1/labels"
tags: ["Labels"]
---

# List labels

`GET /v1/labels`

## Request

- Base URL: `https://api.mails.ai`
- URL: `https://api.mails.ai/v1/labels`
- Auth: HTTP bearer

**Requires scope:** `read`. Every label in the workspace (at most 200), by name.

## Response `200`

The workspace's labels.

- object
  - `data` Label[], required: Every label in the workspace, sorted by name; a workspace has at most 200.
    - `id` string, required: Label id (`lbl_…`).
    - `name` string, required: Unique in the workspace, ignoring case.
    - `color` 'gray' | 'red' | 'orange' | 'amber' | 'yellow' | 'green' | 'teal' | 'cyan' | 'blue' | 'indigo' | 'purple' | 'pink', required: The label's colour, one of 12 palette names: `gray` unless another was chosen.
    - `created_at` string, date-time, required: When the label was created (UTC).
    - `updated_at` string, date-time, required: When the label was last changed with PATCH, even by a request that left it as it was. Equal to `created_at` on a label never patched.
  - `has_more` boolean, required: Always `false`: every label comes in one response.
  - `next_cursor` string: Pass as `cursor` to fetch the next page. Absent on the last page.

## Other responses

- `401`: Missing or invalid API key.
- `403`: The API key lacks the required scope (`insufficient_scope`), or the token belongs to an app connected by sign-in and this operation is closed to connected apps (`connected_app_not_allowed`).
- `500`: Internal server error.

---

[API](https://skmtc.dev/mails/apis/mails-ai-api.md) · [All operations](https://skmtc.dev/mails/apis/mails-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mails/apis/mails-ai-api/revisions/4d4930a8c33b?raw)