> ## Documentation Index
> Fetch the complete documentation index at: https://dev.docs.1to1ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Mailboxes

> Lists the business mailboxes with their category and their channel

<Info>
  **Endpoint** · `GET /mailbox-categories`
</Info>

<Note>
  **Read-only** endpoint: it returns information and changes nothing. It is not sent inside the `actions` array — you call it directly.
</Note>

Lists the active mailboxes of the business in alphabetical order, each one with its category and the channel it belongs to. This is the catalog you use to discover which mailbox or which category to move a conversation to with the `assign_mailbox` action: the `name` returned here is exactly the value that action expects.

<Warning>
  The path is called `mailbox-categories` for historical reasons, but what it returns are **mailboxes**, not categories. Each mailbox's category comes in the `category` field of every item.
</Warning>

The response is paginated with an opaque cursor: while `has_more` is `true`, repeat the call passing the previous page's `next_cursor` in `?cursor=`. Cursors are not shared across different endpoints, even though the format looks the same.

**Parameters**

Every query parameter is optional; with none of them you get the first page of the full catalog. The business `slug` goes in the path and is **required**.

* `search` — case-insensitive substring of the mailbox name. The asterisk `*` works as a wildcard; `%` and `_` are matched literally.
* `category` — returns only the mailboxes in this category, by full name and case-insensitive. Accepts `*` as a wildcard. Mailboxes with no category are excluded, and a non-existent category returns an empty page, not an error.
* `channel` — returns only the mailboxes of this channel, by its public key. This is not a pattern filter: the key is compared exactly against its canonical form —case-insensitive— and `*` is not a wildcard. A non-existent, partial or `*`-containing key returns `404 CHANNEL_NOT_FOUND`.
* `cursor` — opaque cursor returned by the previous page in `next_cursor`. Omit it to request the first page.
* `limit` — mailboxes per page. Default 30, maximum 100.

### Response

```json theme={null}
{
  "items": [
    {
      "name": "Ventas · Turno matutino",
      "category": "Ventas",
      "channel": "ch_7A9K2M4Q"
    },
    {
      "name": "General mailbox",
      "category": null,
      "channel": "ch_7A9K2M4Q"
    }
  ],
  "next_cursor": "eyJuIjoiVmVudGFzIn0",
  "has_more": true
}
```

* `name` — mailbox name. This is what you pass as `mailbox` in `assign_mailbox`.
* `category` — category the mailbox belongs to, or `null` if it has none. Only the default mailbox of each channel can come back as `null`; those are always assigned by `mailbox`.
* `channel` — public key of the channel the mailbox belongs to. A mailbox lives in a single channel, so this field tells you which conversations it can be used on.
* `next_cursor` — cursor for the next page; `null` when `has_more` is `false`.
* `has_more` — whether there are more results after this page.

**Errors**

| HTTP status | Error code                | When                                                                |
| ----------- | ------------------------- | ------------------------------------------------------------------- |
| 400         | `INVALID_REQUEST`         | A query parameter does not match the expected format.               |
| 400         | `INVALID_CURSOR`          | The `cursor` sent is corrupted or does not belong to this endpoint. |
| 401         | `INVALID_API_TOKEN`       | Missing, malformed or invalid token.                                |
| 403         | `TOKEN_BUSINESS_MISMATCH` | The slug in the path does not match the token's business.           |
| 404         | `CHANNEL_NOT_FOUND`       | The key sent in `channel` does not exist.                           |
| 429         | `RATE_LIMIT_EXCEEDED`     | Request rate limit exceeded.                                        |
| 500         | `UNKNOWN_ERROR`           | Unexpected server error.                                            |

### Example

This call is a **read**: it does not create, move or modify any conversation. It only fetches the mailbox catalog so you know which `name` to use later in an action.

```bash theme={null}
curl -X GET "https://app.1to1.ai/api/v1/public/{slug}/mailbox-categories?channel=ch_7A9K2M4Q&limit=30" \
  -H "Authorization: Bearer sk_1to1_your_api_key"
```

With the `name` of a mailbox from this response you can already build the [Assign mailbox](/en/action-groups/assign-mailbox) action, which is the one that actually moves the conversation. If instead of the exact mailbox you pass the `category` from that same response, the platform balances the load and picks the least busy mailbox in the category.