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

# Buzones

> Lista los buzones del business con su categoría y su canal

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

<Note>
  Endpoint de **solo consulta**: devuelve información y no modifica nada. No se manda dentro del array `actions` — se llama directo.
</Note>

Lista los buzones activos del business en orden alfabético, cada uno con su categoría y el canal al que pertenece. Es el catálogo desde el que se descubre a qué buzón o a qué categoría mover una conversación con la acción `assign_mailbox`: el `name` que devuelve esta consulta es exactamente el valor que espera esa acción.

<Warning>
  El path se llama `mailbox-categories` por herencia, pero lo que devuelve son **buzones**, no categorías. La categoría de cada buzón viene en el campo `category` de cada elemento.
</Warning>

La respuesta se pagina por cursor opaco: mientras `has_more` sea `true`, repetir la llamada pasando el `next_cursor` de la página anterior en `?cursor=`. Los cursores no se comparten entre endpoints distintos, aunque el formato se vea igual.

**Parámetros**

Todos los parámetros de consulta son opcionales; sin ninguno se devuelve la primera página del catálogo completo. El `slug` del business va en el path y sí es **obligatorio**.

* `search` — substring del nombre del buzón, sin distinguir mayúsculas. El asterisco `*` funciona como comodín; `%` y `_` se buscan literalmente.
* `category` — devuelve solo los buzones de esta categoría, por nombre completo y sin distinguir mayúsculas. Acepta `*` como comodín. Los buzones sin categoría quedan excluidos, y una categoría inexistente devuelve una página vacía, no un error.
* `channel` — devuelve solo los buzones de este canal, por su clave pública. No es un filtro por patrón: la clave se compara exacta contra su forma canónica —sin distinguir mayúsculas— y el `*` no actúa como comodín. Una clave inexistente, parcial o con `*` devuelve `404 CHANNEL_NOT_FOUND`.
* `cursor` — cursor opaco devuelto por la página anterior en `next_cursor`. Omitir para pedir la primera página.
* `limit` — buzones por página. Default 30, máximo 100.

### Respuesta

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

* `name` — nombre del buzón. Es lo que se pasa como `mailbox` en `assign_mailbox`.
* `category` — categoría a la que pertenece el buzón, o `null` si no tiene. Solo el buzón por defecto de cada canal puede venir en `null`; a esos se les asigna siempre por `mailbox`.
* `channel` — clave pública del canal al que pertenece el buzón. Un buzón vive en un solo canal, así que este campo indica sobre qué conversaciones se puede usar.
* `next_cursor` — cursor de la página siguiente; `null` cuando `has_more` es `false`.
* `has_more` — indica si hay más resultados después de esta página.

**Errores**

| Código HTTP | Código de error           | Cuándo                                                              |
| ----------- | ------------------------- | ------------------------------------------------------------------- |
| 400         | `INVALID_REQUEST`         | Algún parámetro de consulta no cumple el formato esperado.          |
| 400         | `INVALID_CURSOR`          | El `cursor` enviado está corrupto o no corresponde a este endpoint. |
| 401         | `INVALID_API_TOKEN`       | Token ausente, mal formado o no válido.                             |
| 403         | `TOKEN_BUSINESS_MISMATCH` | El slug del path no coincide con el business del token.             |
| 404         | `CHANNEL_NOT_FOUND`       | La clave enviada en `channel` no existe.                            |
| 429         | `RATE_LIMIT_EXCEEDED`     | Se superó el límite de peticiones.                                  |
| 500         | `UNKNOWN_ERROR`           | Error inesperado del servidor.                                      |

### Ejemplo

Esta llamada es una **lectura**: no crea, no mueve ni modifica ninguna conversación. Solo trae el catálogo de buzones para saber qué `name` usar después en una acción.

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

Con el `name` de un buzón de esta respuesta ya se puede armar la acción [Asignar buzón](/es/action-groups/assign-mailbox), que es la que efectivamente mueve la conversación. Si en lugar del buzón exacto se pasa el `category` de esa misma respuesta, la plataforma reparte la carga y elige el buzón menos cargado de la categoría.