# Discover labels

GET /v1/inboxes/{inbox_id}/labels

Source: https://cherami.to/docs/api/labels/list-labels



{/* Generated from apps/web/openapi. Edit the contract, not this file. */}

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

Requires an [API key](https://cherami.to/docs/api#authentication): `Authorization: Bearer YOUR_CREDENTIAL`.

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.

## Parameters [#parameters]

| Parameter  | Location | Required | Type    | Meaning                                                                                                      |
| ---------- | -------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------ |
| `inbox_id` | path     | Yes      | string  | Cherami resource ID returned by the API.                                                                     |
| `limit`    | query    | No       | integer | Results per page. `minimum`: `1` `maximum`: `100` `default`: `20`                                            |
| `cursor`   | query    | No       | string  | next\_cursor from the previous page. Keep the URL, filters and order unchanged.                              |
| `prefix`   | query    | No       | string  | Only names starting with this text, case-sensitive; empty means all. At most 128 UTF-8 bytes, supplied once. |

## curl example [#curl-example]

Supply `CHERAMI_API_KEY` privately.

```sh
curl --silent --show-error --include --request GET \
  "https://cherami.to/v1/inboxes/INBOX_ID/labels" \
  --header "Authorization: Bearer $CHERAMI_API_KEY"
```

## Responses [#responses]

### HTTP 200 [#http-200]

Success.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[LabelList](#schema-labellist)

```json
{
  "labels": [],
  "next_cursor": null
}
```

### HTTP 400 [#http-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.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 401 [#http-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).

* `X-Request-ID`: Identifies this request; include it when reporting a problem.
* `WWW-Authenticate`: `"Bearer"`

Content type: `application/json`.

[Error](#schema-error)

### HTTP 404 [#http-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.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 500 [#http-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.

* `X-Request-ID`: Identifies this request; include it when reporting a problem.

Content type: `application/json`.

[Error](#schema-error)

## Schema: LabelList [#schema-labellist]

| Field         | Required | Type            | Meaning and constraints |
| ------------- | -------- | --------------- | ----------------------- |
| `labels`      | Yes      | array of object |                         |
| `next_cursor` | Yes      | string or null  |                         |

### `labels` fields [#labels-fields]

| Field            | Required | Type    | Meaning and constraints |
| ---------------- | -------- | ------- | ----------------------- |
| `name`           | Yes      | string  |                         |
| `received_count` | Yes      | integer | `minimum`: `0`          |
| `sent_count`     | Yes      | integer | `minimum`: `0`          |

## Schema: Error [#schema-error]

| Field   | Required | Type   | Meaning and constraints |
| ------- | -------- | ------ | ----------------------- |
| `error` | Yes      | object |                         |

### `error` fields [#error-fields]

| Field     | Required | Type   | Meaning and constraints                                               |
| --------- | -------- | ------ | --------------------------------------------------------------------- |
| `code`    | Yes      | string | Code to handle. Handle a code you don't recognize by its HTTP status. |
| `message` | Yes      | string | Explanation of this case; its wording can change.                     |

[Errors, limits and pagination](https://cherami.to/docs/api/errors) · [Download OpenAPI 3.1](https://cherami.to/openapi.json)
