---
title: "Discover labels"
method: GET
path: "/v1/inboxes/{inbox_id}/labels"
tags: ["labels"]
---

# Discover labels

`GET /v1/inboxes/{inbox_id}/labels`

## Request

- Base URL: `https://cherami.to`
- URL: `https://cherami.to/v1/inboxes/{inbox_id}/labels`
- Auth: HTTP bearer

Lists the label names in use on the inbox's received and sent mail, with how many messages carry each in `received_count` and `sent_count`. `prefix` narrows the list to names starting with it, case-sensitive.

A name disappears once no message carries it. There is no separate step to create, rename or delete a label: add or remove it on messages.

## Path parameters

- `inbox_id` string, required

## Query parameters

- `limit` integer
- `cursor` string
- `prefix` string

## Response `200`

Success.

- LabelList
  - `labels` object[], required
    - `name` string, required
    - `received_count` integer, required
    - `sent_count` integer, required
  - `next_cursor` string, nullable, required

## Other responses

- `400`: `invalid_limit`: Use an integer from 1 to 100. `invalid_cursor`: Send a cursor only to the listing, filters and order that returned it, or restart from the first page. `invalid_labels`: Correct the label name, label change, filter group or discovery prefix the message names.
- `401`: `unauthorized`: Send a valid API key as `Authorization: Bearer <key>`. If the key stopped working, get a new one through [recovery](https://cherami.to/docs/guides/recovery).
- `404`: `not_found`: The resource does not exist or does not belong to this account. A reply or forward source must also be in the sending inbox.
- `500`: `internal_error`: The operation failed. Retry a read; after a write the change may have happened, so recover as [retry by operation](https://cherami.to/docs/api/errors#retry-by-operation) describes.

---

[API](https://skmtc.dev/cherami/apis/cherami-http-api.md) · [All operations](https://skmtc.dev/cherami/apis/cherami-http-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cherami/apis/cherami-http-api/revisions/7bd993d538af?raw)