> ## 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.

# Caixas de entrada

> Lista as caixas de entrada do business com sua categoria e seu canal

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

<Note>
  Endpoint **somente de consulta**: devolve informação e não modifica nada. Não é enviado dentro do array `actions` — é chamado diretamente.
</Note>

Lista as caixas de entrada ativas do business em ordem alfabética, cada uma com sua categoria e o canal ao qual pertence. É o catálogo a partir do qual se descobre para qual caixa de entrada ou para qual categoria mover uma conversa com a ação `assign_mailbox`: o `name` devolvido por esta consulta é exatamente o valor que essa ação espera.

<Warning>
  O path se chama `mailbox-categories` por herança, mas o que ele devolve são **caixas de entrada**, não categorias. A categoria de cada caixa de entrada vem no campo `category` de cada item.
</Warning>

A resposta é paginada por cursor opaco: enquanto `has_more` for `true`, repetir a chamada passando o `next_cursor` da página anterior em `?cursor=`. Os cursores não são compartilhados entre endpoints diferentes, mesmo que o formato pareça igual.

**Parâmetros**

Todos os parâmetros de consulta são opcionais; sem nenhum deles é devolvida a primeira página do catálogo completo. O `slug` do business vai no path e é **obrigatório**.

* `search` — substring do nome da caixa de entrada, sem diferenciar maiúsculas. O asterisco `*` funciona como curinga; `%` e `_` são buscados literalmente.
* `category` — devolve apenas as caixas de entrada desta categoria, por nome completo e sem diferenciar maiúsculas. Aceita `*` como curinga. As caixas de entrada sem categoria ficam excluídas, e uma categoria inexistente devolve uma página vazia, não um erro.
* `channel` — devolve apenas as caixas de entrada deste canal, pela sua chave pública. Não é um filtro por padrão: a chave é comparada de forma exata contra sua forma canônica —sem diferenciar maiúsculas— e o `*` não atua como curinga. Uma chave inexistente, parcial ou com `*` devolve `404 CHANNEL_NOT_FOUND`.
* `cursor` — cursor opaco devolvido pela página anterior em `next_cursor`. Omitir para pedir a primeira página.
* `limit` — caixas de entrada por página. Padrão 30, máximo 100.

### Resposta

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

* `name` — nome da caixa de entrada. É o que se passa como `mailbox` em `assign_mailbox`.
* `category` — categoria à qual a caixa de entrada pertence, ou `null` se não tiver. Somente a caixa de entrada padrão de cada canal pode vir como `null`; a essas sempre se atribui por `mailbox`.
* `channel` — chave pública do canal ao qual a caixa de entrada pertence. Uma caixa de entrada vive em um único canal, então este campo indica sobre quais conversas ela pode ser usada.
* `next_cursor` — cursor da página seguinte; `null` quando `has_more` for `false`.
* `has_more` — indica se há mais resultados depois desta página.

**Erros**

| Código HTTP | Código de erro            | Quando                                                                 |
| ----------- | ------------------------- | ---------------------------------------------------------------------- |
| 400         | `INVALID_REQUEST`         | Algum parâmetro de consulta não cumpre o formato esperado.             |
| 400         | `INVALID_CURSOR`          | O `cursor` enviado está corrompido ou não corresponde a este endpoint. |
| 401         | `INVALID_API_TOKEN`       | Token ausente, mal formado ou inválido.                                |
| 403         | `TOKEN_BUSINESS_MISMATCH` | O slug do path não coincide com o business do token.                   |
| 404         | `CHANNEL_NOT_FOUND`       | A chave enviada em `channel` não existe.                               |
| 429         | `RATE_LIMIT_EXCEEDED`     | Limite de requisições excedido.                                        |
| 500         | `UNKNOWN_ERROR`           | Erro inesperado do servidor.                                           |

### Exemplo

Esta chamada é uma **leitura**: não cria, não move nem modifica nenhuma conversa. Apenas traz o catálogo de caixas de entrada para saber qual `name` usar depois em uma ação.

```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_sua_api_key"
```

Com o `name` de uma caixa de entrada desta resposta já é possível montar a ação [Atribuir caixa de entrada](/pt/action-groups/assign-mailbox), que é a que efetivamente move a conversa. Se, em vez da caixa de entrada exata, for passado o `category` dessa mesma resposta, a plataforma distribui a carga e escolhe a caixa de entrada menos carregada da categoria.