---
title: Bandejas de entrada
description: Direcciones de email que guardan el correo en hilos y responden desde la misma dirección, para un agente de IA o para personas.
seo:
  title: Bandejas de entrada para agentes de IA
ai:
  exclude: true
---

Una bandeja de entrada es una dirección de email que recibe correo en hilos y envía desde esa misma dirección. Dásela a un agente de IA, que la lee con la API, los webhooks o el [servidor MCP](/docs/es/mcp), o a personas, que la leen en el panel. Una bandeja es una dirección en uno de tus [dominios de recepción](/docs/es/receiving), o una dirección en el dominio compartido de BillionSend, que no necesita DNS.

Los [SDK](/docs/es/sdks) cubren todos los endpoints de bandejas como `inboxes.*`, incluidas las reglas de seguridad, la cuarentena, las aprobaciones y el flujo de eventos en directo.

> **Info**
>
> Las bandejas de entrada están en beta, en **Bandejas de entrada** del panel.

## Agente o personas

Cada bandeja tiene un `kind`, que se elige al crearla y no cambia nunca. El tipo fija los valores por defecto de los ajustes de seguridad.

| Ajuste | Agente | Personas |
| --- | --- | --- |
| `accept_from` | `verified` | `anyone` |
| `screening` | activado | desactivado |
| `extract_codes` | activado | activado |
| `send_policy` | `reply_only` | `open` (`reply_only` en el dominio compartido) |
| `require_approval` | desactivado | desactivado |
| `private_codes` | activado | desactivado |
| `send_cap` | 200 (50 en el dominio compartido) | ninguno (50 en el dominio compartido) |

- **`agent`** es el valor por defecto cuando se omite `kind`. El correo de remitentes cuyo dominio no responde por ellos espera en cuarentena, el correo de otros remitentes externos se revisa en busca de inyección de prompts, y el agente responde dentro de los hilos existentes: una conversación nueva que empieza se convierte en un borrador que espera a una persona. Consulta [Seguridad del agente](/docs/es/agent-safety).
- **`human`** es para personas que leen en el panel: se entrega el correo de todo el mundo (una autenticación fallida va a la carpeta `spam`) y no se revisa nada.

El correo con un virus se pone en cuarentena en todas las bandejas.

## Crear una bandeja de entrada

En el panel, abre **Bandejas de entrada** y elige **Crear bandeja de entrada**. O llama a la API:

```sh
curl -X POST "https://api.billionsend.com/inboxes" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email_address": "orders@inbound.example.com",
    "name": "Orders agent",
    "kind": "agent"
  }'
```

Con el SDK de Node.js:

```ts
import { BillionSend } from "@billionsend/node";

const bs = new BillionSend(); // reads BILLIONSEND_API_KEY

const { data, error } = await bs.inboxes.create({
  email_address: "orders@inbound.example.com",
  name: "Orders agent",
  kind: "agent",
});
```

La respuesta (`201`) es la bandeja completa: `id`, `name`, `email_address`, `domain_id`, `kind`, `shared`, `expires_at`, `unread` (hilos con un mensaje sin leer), `drafts`, `quarantined`, `pending_approval` y más.

| Campo | Reglas |
| --- | --- |
| `email_address` | Una dirección en un dominio verificado de tu equipo que recibe correo. En minúsculas; la parte anterior a `@` admite hasta 64 letras, dígitos y `. _ % + -`. No se puede cambiar después. Omítela para una dirección en el dominio compartido. |
| `username` | Si se omite `email_address`, la parte anterior a `@` en el dominio compartido; si también se omite, la dirección es aleatoria. Con un `domain_id` de uno de tus dominios, es la parte anterior a `@` en él. |
| `domain_id` | Una fila de `GET /domains`: el subdominio compartido de tu equipo (`shared: true`) o uno de tus dominios verificados. |
| `name` | De 1 a 320 caracteres; la dirección si se omite. |
| `from_name` | Nombre visible del correo que envía la bandeja, de hasta 78 caracteres: un nombre sencillo, sin `@`, `:`, `<`, `>`, saltos de línea, enlaces ni teléfonos. |
| `kind` | `agent` (por defecto) o `human`. |
| `expires_in` | Cuándo caduca la bandeja, como `1h`, `24h` o `7d`; si se omite, nunca. |
| `safety` | Cualquiera de los ajustes de seguridad. |
| `forwarding` | `true` añade un `receiving_address` en el dominio compartido, para reenviar a la bandeja un buzón que mantienes en otro sitio. |

| Respuesta | Cuándo |
| --- | --- |
| `409 validation_error` | Otra bandeja ya usa la dirección. No se elige otro nombre por ti. |
| `403 validation_error` | Se alcanzó el límite de bandejas de tu plan. |
| `429 rate_limit_exceeded` | Se crearon demasiadas bandejas en la última hora, o la revisión de nombres del dominio compartido alcanzó el límite de hoy. `retry-after` indica cuándo reintentar. |
| `422 validation_error` | El dominio no está verificado o no recibe correo, un `username` incumple una regla o está reservado, o un ajuste incumple una regla. |
| `503 name_review_unavailable` | No se pudo revisar ahora un nombre del dominio compartido. Inténtalo de nuevo en breve. |

Las demás llamadas:

- `GET /inboxes` lista las bandejas, de la más reciente a la más antigua (`?kind=agent` o `?kind=human` lo acota).
- `GET /inboxes/{id}` lee una. Cada `{id}` de una ruta `/inboxes/{id}/…` admite el id de la bandeja o su dirección de email.
- `PATCH /inboxes/{id}` cambia `name`, `from_name` o `expires_in`.
- `DELETE /inboxes/{id}` elimina la bandeja con sus hilos, borradores y etiquetas, y revoca sus claves de API. Un mensaje que también llegó a otra bandeja o a una dirección catch-all se queda allí.

## Direcciones

### Tu propio dominio

Una bandeja en tu propio dominio necesita que el dominio [reciba correo](/docs/es/receiving): verificado, con la recepción activada y su registro MX publicado. Cada mensaje sigue la dirección a la que lo entregó el servidor del remitente:

1. a la bandeja con exactamente esa dirección;
2. si no, para `name+tag@`, a la bandeja de `name@`;
3. si no, cuando catch-all del dominio está activado, a **Todo lo recibido** sin bandeja; con catch-all desactivado, la dirección se rechaza (`550 5.1.1`).

El correo enviado desde la dirección de una bandeja sigue las reglas de la bandeja en todas las vías: `POST /emails`, el endpoint por lotes, el relay SMTP y MCP. Dale a una bandeja una dirección desde la que tu app aún no envíe.

### Dominio compartido

Una bandeja en el dominio compartido no necesita DNS. Cada equipo tiene su propio subdominio en el dominio compartido de BillionSend, con el nombre del equipo. Omite `email_address`, o envía el id de la fila compartida como `domain_id`, y `username` da nombre a la dirección:

```sh
curl -X POST "https://api.billionsend.com/inboxes" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{ "username": "orders", "name": "Orders agent" }'
```

Sin `username`, la dirección es aleatoria. Un nombre de usuario se rechaza (`422`) cuando está reservado (postmaster, abuse, admin, security, support, noreply, no-reply, billing, hostmaster, webmaster, mailer-daemon, root), empieza por `fwd-` o parece una marca conocida. Si ya está en uso, responde `409`.

**Revisión de nombres.** Un nombre de usuario elegido, un `from_name` y el subdominio del equipo se revisan antes de publicarse, para frenar los nombres que se hacen pasar por una marca, un banco, un gobierno o un cargo oficial. Un nombre rechazado responde `422`. Mientras la revisión no puede responder, recibes `503 name_review_unavailable`; el subdominio de un equipo nuevo se reintenta hasta que pasa, y pasadas 24 horas el equipo toma `team-` y seis caracteres aleatorios. Superados 20 nombres rechazados o 200 revisiones en un día UTC, la respuesta es `429` hasta medianoche UTC.

Las direcciones compartidas siguen reglas propias, porque el dominio es de todos los equipos:

- Duran hasta que se eliminan, salvo que `expires_in` diga otra cosa, y cuentan para el límite de bandejas de tu plan. Una que nadie usa en 90 días se elimina.
- En el plan **Free**, y para cualquier dirección cuyo nombre parezca una marca conocida, solo responden dentro de sus propios hilos, a remitentes cuyo dominio respondió por ellos y a las direcciones de inicio de sesión de los miembros de tu equipo. En un plan de pago, las personas inician conversaciones desde ellas, y un agente lo hace cuando su `send_policy` es `open` y tu equipo ha superado sus primeros envíos; si no, sus conversaciones nuevas esperan a una persona como borradores. Cada mensaje a un desconocido se comprueba contra phishing antes de salir. Un rechazo responde `403 inbox_send_policy`.
- Cada email va a 10 destinatarios como máximo. Una bandeja envía a 50 destinatarios al día como máximo (`send_cap` de 1 a 50), y todas las direcciones compartidas de tu equipo juntas llegan a 1000 destinatarios por día UTC; superado, `429 inbox_send_cap_reached`.
- `from` debe ser exactamente la dirección de la bandeja, y el email no puede llevar `scheduled_at`, `reply_to`, adjuntos ni cabeceras personalizadas (`422`). `POST /emails/batch`, los envíos masivos y el relay SMTP rechazan siempre una dirección compartida.
- `forward_to` admite solo direcciones de inicio de sesión de miembros.

El correo a `postmaster@` y `abuse@` en el dominio compartido va a BillionSend, nunca a una bandeja.

### Reenviar un buzón a una bandeja

`forwarding: true` es para una dirección cuyo correo vive en otro sitio, como un buzón de Google Workspace. La bandeja recibe un `receiving_address`, una dirección aleatoria en el subdominio compartido de tu equipo: reenvía el buzón allí y la bandeja recibe el correo mientras responde desde su propia dirección. Entonces el dominio solo necesita estar verificado para enviar.

## Caducidad

`expires_in` es un número seguido de `h` o `d`, de `1h` a `365d`; si se omite, la bandeja no caduca nunca. Un `PATCH` con un `expires_in` nuevo cuenta desde ese momento, y `null` elimina la caducidad. `expires_at` muestra cuándo termina.

En `expires_at` la bandeja se detiene: el correo que le llega se rechaza (`550 5.1.1`), las lecturas responden `404` y sus claves de API dejan de funcionar. Dentro de la hora se elimina, con un webhook `inbox.expired` seguido de `inbox.deleted`. Cambiar la caducidad requiere el rol de desarrollador, administrador o propietario.

## Hilos

Cada mensaje de una bandeja pertenece a un hilo, y un hilo contiene ambas direcciones: lo que la bandeja recibió y lo que envió.

- **Cómo encuentran las respuestas su hilo.** El correo que envía la bandeja lleva un token de hilo en su cabecera `References`. Una respuesta cae en el mismo hilo cuando lleva ese token, cuando su `In-Reply-To` nombra un mensaje que envió la bandeja, o cuando hace referencia a un mensaje anterior del hilo. Los asuntos nunca unen hilos.
- **Carpetas.** Un hilo está en una carpeta: `inbox`, `archive`, `spam`, `sent` o `trash`. El correo nuevo devuelve a `inbox` un hilo archivado o enviado. `DELETE` mueve un hilo a `trash`, que se vacía a los 30 días.
- **Estado de lectura.** Un `PATCH` con `read` marca el hilo entero. El correo retenido nunca deja un hilo sin leer. En una bandeja de personas, abrir un hilo lo marca como leído; en una bandeja de agente, el estado de lectura es de tu agente.
- **Etiquetas.** Hasta 100 por bandeja, con nombres de 1 a 64 caracteres y colores como `#RRGGBB`.

| Llamada | Hace |
| --- | --- |
| `GET /inboxes/{id}/threads` | Lista los hilos, con la actividad más reciente primero. Filtros: `folders`, `labels`, `read`, `include_quarantined`. |
| `GET /inboxes/{id}/threads/search` | Los mismos filtros más `query` (`"frase exacta"` y `-excluido` funcionan), `from`, `to`, `cc`, `bcc`, `has_attachment`, `start_date`, `end_date`. |
| `GET /inboxes/{id}/threads/{thread_id}` | Un hilo. |
| `PATCH /inboxes/{id}/threads/{thread_id}` | Fija `read` o `folder`. |
| `POST` / `PUT` / `DELETE …/threads/{thread_id}/labels` | Añade, sustituye o quita etiquetas. |
| `DELETE /inboxes/{id}/threads/{thread_id}` | Mueve el hilo a la papelera. |
| `GET /inboxes/{id}/threads/{thread_id}/emails` | Sus emails, del más antiguo al más reciente. |

La búsqueda coincide con palabras completas, sin distinguir mayúsculas, en el asunto, el remitente (dirección y nombre visible), los destinatarios, el texto de un email recibido (incluidos los mensajes anteriores que cita), los nombres de sus adjuntos y el texto de sus adjuntos PDF, Word y Excel (una vez leído ese texto). El texto en chino, japonés y coreano se divide en palabras. Cada palabra de `query` debe coincidir en algún punto del mismo email; `from`, `to`, `cc` y `bcc` admiten palabras de una dirección o de un nombre. Los emails enviados se buscan por asunto, remitente y destinatarios.

`matched_email_id` es la mejor coincidencia del hilo, y `highlights` marca las palabras en su asunto, remitente y destinatarios (vale `{}` cuando solo coincidió el texto o el nombre de un adjunto). Un email nuevo se puede buscar uno o dos segundos después de llegar. Si la búsqueda no está disponible un momento, la llamada responde `503` con `search_unavailable` y una cabecera `Retry-After`; todas las demás llamadas funcionan con normalidad.

Un email de un hilo tiene `direction`, `from`, `to`, `cc`, `bcc`, `reply_to`, `subject`, `message_id`, `html`, `text`, `attachments`, `read` y `received_at`. El correo recibido añade `extracted_text` (la respuesta, limpia de texto oculto), `screening`, `spam_verdict` y `virus_verdict`.

## Enviar desde una bandeja

`POST /inboxes/{id}/emails` (`inboxes.send()` en los SDK) inicia una conversación nueva desde la dirección de la bandeja en una sola llamada.

```sh
curl -X POST "https://api.billionsend.com/inboxes/{id}/emails" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-confirmation" \
  -d '{
    "to": "success@simulator.amazonses.com",
    "subject": "Tu pedido 1042",
    "text": "Sale hoy. La factura va adjunta.",
    "attachments": [{ "filename": "invoice.pdf", "content": "JVBERi0xLjQK..." }]
  }'
```

Admite `to`, `subject`, `html` y/o `text`, y opcionalmente `cc`, `bcc`, `attachments` y `requires_approval`. Las reglas de la bandeja deciden como en una respuesta, y las respuestas son las de una respuesta: `200` con `{ "id", "thread_id" }`, o `202` con el borrador cuando las reglas retienen el envío (una bandeja que no puede iniciar conversaciones, un destinatario nuevo fuera del ritmo permitido, `requires_approval: true`). Una clave restringida a una bandeja puede llamarlo para su propia bandeja.

Los **adjuntos** son los que admite `POST /emails`: `filename` y `content` en base64, y opcionalmente `content_type` y `content_id` para una imagen en línea. Un `path` remoto responde `422`. Las respuestas, los reenvíos, los envíos nuevos y los borradores los admiten, hasta 10 MiB decodificados en total (un reenvío cuenta también los archivos del original); los programas y los tipos de archivo disfrazados responden `422`, y una bandeja del dominio compartido no admite ninguno.

## Responder y reenviar

```sh
curl -X POST "https://api.billionsend.com/inboxes/{id}/threads/{thread_id}/emails/{email_id}/reply" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-reply" \
  -d '{ "text": "Gracias, tu pedido sale hoy." }'
```

Una respuesta va al `Reply-To` del mensaje o, si no hay, a su remitente. `reply_all` añade las demás direcciones de `to` y `cc` como `cc`; `bcc` nunca se copia. Un envío admite 50 destinatarios como máximo. `…/forward` requiere `to`, admite una nota y cita el original con sus adjuntos, más los `attachments` que añadas (hasta 10 MiB en total). Ambos admiten `attachments` y `requires_approval: true` para que una persona apruebe el envío. Una respuesta de una bandeja de agente lleva `Auto-Submitted: auto-replied`.

| Respuesta | Significa |
| --- | --- |
| `200` | Enviado: `{ "id", "thread_id" }`. |
| `202` | Retenido para una persona: el borrador, con `status: "pending_approval"` y sus `approval_reasons`. |
| `403 inbox_send_policy` | Las reglas de la bandeja rechazan el envío sin más. |
| `403 email_quarantined` | El email está retenido en cuarentena, o lleva un virus. |
| `403 restricted_api_key` | Una clave restringida a una bandeja intenta llegar a otra bandeja. |
| `429 inbox_send_cap_reached` | Se agotó el tope diario de la bandeja; `retry-after` cuenta hasta medianoche UTC. |

Para responder a cualquier email recibido, esté o no en una bandeja, usa [`POST /emails/receiving/{id}/reply`](/docs/es/receiving).

## Borradores y aprobación

Un borrador es independiente si es una conversación nueva, o una respuesta con `thread_id` y `reply_to_email_id`. Su `status`:

| `status` | Significa |
| --- | --- |
| `draft` | Se está escribiendo; nada lo envía hasta `…/send` o hasta su `send_at`. |
| `pending_approval` | Un envío quedó retenido y espera a una persona. `approval_reasons` dice por qué. Caduca a los 7 días. |
| `sent` | Enviado; `email_id` nombra el email. |
| `rejected` | Una persona lo rechazó. |
| `expired` | Nadie lo aprobó en 7 días. |

| Llamada | Hace |
| --- | --- |
| `POST /inboxes/{id}/drafts` | Crea un borrador: `to`, `cc`, `bcc`, `subject`, `text`, `html`, `attachments`, más `thread_id` y `reply_to_email_id` para una respuesta. Un borrador de respuesta no copia los destinatarios, así que fija `to` antes de enviar. |
| `GET /inboxes/{id}/drafts` | Los borradores sin enviar, el actualizado más recientemente primero. |
| `GET` / `PATCH` / `DELETE /inboxes/{id}/drafts/{draft_id}` | Lee, cambia (fijar `text` o `html` sustituye todo el cuerpo, y `attachments` sustituye toda la lista) o elimina un borrador; `409` una vez enviado. |
| `POST /inboxes/{id}/drafts/{draft_id}/send` | Lo envía. `200` con el `id` y el `thread_id` del email enviado, `202` si queda retenido, `422` sin destinatario. |
| `POST /inboxes/{id}/drafts/{draft_id}/reject` | Rechaza un borrador (solo quienes aprueban). |

Un borrador guarda sus `attachments` cifrados, aparte de su cuerpo, y los devuelve por posición como `id`, `filename`, `content_type` y `size`, nunca el contenido. Salen con el email cuando se envía el borrador, y un envío retenido conserva con su borrador los archivos que llevaba. Cuando un borrador se envía, se rechaza, caduca o se elimina, sus archivos desaparecen, y la purga de contenido a los 30 días elimina los que queden.

**Envíos programados.** `send_at` en `POST` o `PATCH` (una extensión de BillionSend) envía el borrador más tarde, como quien lo fijó (editar el contenido de un borrador programado hace que quien edita sea quien lo envía): una hora ISO 8601 con desfase, o una relativa como `"in 2 hours"`, con 30 días de antelación como máximo; una hora ya pasada lo envía en un minuto, y `null` lo cancela. El borrador necesita un destinatario para entonces, y solo un `draft` se puede programar: uno que espera aprobación responde `409`. Cuando llega `send_at`, el envío aplica todas las reglas y límites como lo haría un envío hecho en ese momento. Si se envía, el borrador pasa a `sent`; si lo retienen las reglas de la bandeja, a `pending_approval`; si se rechaza (se revocó la clave que lo programó, la bandeja ya no existe, se alcanzó un límite), sigue como `draft` con `send_at` otra vez en `null`, el nombre del rechazo en `send_error` y un webhook `inbox.draft.send_failed` que lleva `error: { name, message }`. Programarlo de nuevo borra `send_error`. Con `send_at`, crear un segundo borrador de respuesta para el mismo email responde `409` en lugar de devolver el borrador existente.

**Quién aprueba.** Una persona en el panel, o una clave de API de acceso total del equipo que no esté restringida a una bandeja, aprueba enviando: el envío se salta las reglas que retienen el correo del agente. Un agente no puede aprobar: una clave restringida a una bandeja o un cliente MCP que envía un borrador pendiente recibe `403 approval_required`. En el panel, cualquier miembro aprueba, edita o descarta borradores en la pestaña **Pendientes de revisión** de la bandeja, y los propietarios reciben un email al día mientras algo espera.

Motivos por los que se retiene un envío:

| Motivo | Se retiene porque |
| --- | --- |
| `approval_required` | La petición pidió una persona (`requires_approval: true`). |
| `require_approval` | La bandeja tiene todos los envíos con aprobación. |
| `send_policy` | La política de envío de la bandeja no permite a un destinatario. |
| `ramp` | Demasiados destinatarios nuevos hoy para una bandeja reciente. |
| `private_code` | Contiene un código o un enlace de inicio de sesión que recibió la bandeja. |
| `loop_guard:<reason>` | Responde a un mensaje automático (fuera de la oficina, lista de correo, rebote). |
| `loop_burst` | Demasiadas respuestas automáticas a una misma dirección en una hora. |
| `reply_to_redirect` | El Reply-To del mensaje apunta a otra organización. |

## Ajustes de seguridad

`GET /inboxes/{id}/safety` lee las reglas de una bandeja, y `PATCH` cambia cualquiera de ellas:

```sh
curl -X PATCH "https://api.billionsend.com/inboxes/{id}/safety" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "accept_from": "allowlist",
    "allowlist": ["*@billing.example.net", "maria@example.org"]
  }'
```

| Ajuste | Hace |
| --- | --- |
| `accept_from` | Qué correo llega a la bandeja: `anyone`; `verified`, remitentes cuyo dominio responde por la dirección From (más los propietarios, la lista de permitidos y los hilos conocidos); o `allowlist`, solo los propietarios, la lista de permitidos y los hilos conocidos. Lo demás se pone en cuarentena. |
| `allowlist` | Hasta 500 entradas: `name@domain`, o `*@domain` para un dominio y sus subdominios. |
| `owner_addresses` | Hasta 50 direcciones más que se tratan como propietarias de la bandeja, además de las direcciones de inicio de sesión de los miembros de tu equipo. Se ignora en el dominio compartido. |
| `screening` | Puntúa el correo de remitentes externos en busca de inyección de prompts y phishing (bandejas de agente). |
| `extract_codes` | Extrae códigos de verificación y enlaces de inicio de sesión del correo. |
| `send_policy` | `reply_only`; `allowlist`, que añade conversaciones nuevas con los propietarios y la lista de permitidos (no en el dominio compartido); u `open`, cualquiera, una vez que el equipo ha superado sus primeros envíos. |
| `require_approval` | Todo envío desde la bandeja espera a una persona. |
| `private_codes` | Un código o enlace de inicio de sesión que recibió la bandeja no se puede enviar a nadie más que a los propietarios y la lista de permitidos. |
| `send_cap` | Destinatarios a los que la bandeja puede enviar por día UTC sin una persona: de 1 a 100.000, o `null` para no tener tope (de 1 a 50 en el dominio compartido). |
| `forward_to` | Hasta 5 direcciones que reciben una copia de cada mensaje entregado excepto el spam: direcciones de inicio de sesión de miembros del equipo o direcciones propietarias. Una copia que no puede salir enseguida se reintenta hasta que se envía, se rechaza de forma definitiva o pasan dos días; nunca se envía dos veces. |

Un ajuste que incumple una regla responde `422` con el motivo. Una clave restringida a una bandeja no puede cambiar estos ajustes (`403 restricted_api_key`), ni tampoco una clave de agente. Un cliente MCP puede leerlos, pero no cambiarlos. Solo un propietario, administrador o desarrollador los cambia, en el panel o con una clave de API de acceso total. [Seguridad del agente](/docs/es/agent-safety) explica qué hace cada uno.

## Cuarentena

El correo que las reglas de una bandeja no dejan entrar se pone en cuarentena: se conserva, se lista y se puede liberar; nunca se descarta ni se devuelve a su remitente. No dispara `email.received` ni `inbox.email.received` hasta que se libera, y los agentes nunca lo ven.

`GET /inboxes/{id}/quarantine` lista los mensajes retenidos con `id`, `from`, `subject`, `quarantine_reason`, `sender_trust`, `injection_score`, `phishing_score` y `virus_signature`, sin contenido. `POST /inboxes/{id}/quarantine/{email_id}/release` entrega uno, y `{ "trust_sender": true }` añade además a su remitente a la lista de permitidos. Ambos requieren una clave de acceso total no restringida a una bandeja. Las personas liberan desde la pestaña **Pendientes de revisión** de la bandeja, y los clientes MCP con `receiving:manage` usan `release_email`. Quién puede liberar cada retención está en [Seguridad del agente](/docs/es/agent-safety).

## Códigos de verificación

`GET /inboxes/{id}/codes/latest` responde con el código de verificación o enlace de inicio de sesión más reciente que recibió la bandeja, para que un agente nunca lea HTML:

```sh
curl "https://api.billionsend.com/inboxes/{id}/codes/latest?from=example.org&wait=30" \
  -H "Authorization: Bearer bs_..."
```

```json
{
  "object": "verification_code",
  "status": "found",
  "kind": "link",
  "code": null,
  "url": "https://app.example.org/verify?token=Qm9vdHN0cmFwLTQ4MjkxMw",
  "link_domain_matches_sender": true,
  "email_id": "155252fb-e93e-45ee-8c19-5080a929c28b",
  "from": "no-reply@example.org",
  "received_at": "2026-10-12T14:03:11.229Z",
  "sender_trust": "external"
}
```

- `kind` es `otp` (código en `code`) o `link` (dirección en `url`, con `link_domain_matches_sender`).
- `from` lo acota a un remitente; `wait` (de 0 a 50 segundos) espera a que llegue uno; `max_age` (de 60 a 86.400 segundos, 600 por defecto) omite los códigos más antiguos; `since` omite el correo recibido en o antes de esa hora, así que pasa el `received_at` de un código que ya usaste para esperar el siguiente.
- `status` es `found`, `none`, `ambiguous` (dos códigos igual de probables, así que no se responde ninguno) o `timeout`. La respuesta es siempre `200`.
- Los códigos nunca salen de correo en cuarentena, de remitentes que fallaron la autenticación ni de una bandeja con `extract_codes` desactivado. Cada lectura queda registrada en la actividad de la bandeja.

## Flujo de eventos

`GET /inboxes/events` es un flujo de eventos enviados por el servidor (SSE) con todo lo que ocurre en tus bandejas, en el momento en que se confirma. Los eventos llevan los nombres de evento de los webhooks (`inbox.email.received`, `inbox.thread.created`, `inbox.draft.created`, `email.received` y los demás eventos `inbox.*`) y el `data` de la carga del webhook. `GET /inboxes/{id}/events` transmite una sola bandeja y termina cuando esa bandeja se elimina o caduca.

```sh
curl -N "https://api.billionsend.com/inboxes/events?types=inbox.email.received" \
  -H "Authorization: Bearer bs_..." \
  -H "Accept: text/event-stream"
```

```text
retry: 1000

id: 812.40.1790000000
event: inbox.email.received
data: {"type":"inbox.email.received","created_at":"2026-11-15T09:20:30.131Z","inbox_id":"7eeb9517-aed7-40d7-ad65-500be42ed147","data":{"source":"system","inbox_id":"7eeb9517-aed7-40d7-ad65-500be42ed147","thread_id":"...","email_id":"...","email":{}}}

: keepalive
```

- Envía la clave como cabecera `Bearer`, como en cualquier petición. El `EventSource` de los navegadores no puede fijarla: usa `fetch` y lee el cuerpo, o cualquier cliente SSE que admita cabeceras.
- `types` acota el flujo a algunos eventos, separados por comas; `/inboxes/{id}/events` sigue enviando `inbox.deleted` e `inbox.expired`, los eventos que lo terminan. Todo evento lleva solo metadatos, como un webhook: sin cuerpo, código ni enlace. Lee el mensaje con los endpoints de [recepción](/docs/es/receiving).
- **Reanudar.** Todo evento tiene un `id`. Un cliente que se reconecta con `Last-Event-ID` (o `?last_event_id=`) recibe lo que se perdió, en orden, antes de los eventos en directo. Los eventos se conservan 24 horas; una reconexión desde un id más antiguo recibe primero un evento `stream.gap`, que significa que pueden faltar eventos y que hay que volver a leer las listas.
- Un flujo empieza sin reproducción cuando no tiene `Last-Event-ID`. El servidor lo cierra cada 10 minutos más o menos, y cuando la API se reinicia: reconéctate con el último `id` que viste. `retry: 1000` pide al cliente que espere un segundo. Una línea de comentario cada 15 segundos evita que los proxies cierren un flujo inactivo.
- Una clave de todo el equipo abre `/inboxes/events`. Una clave restringida a un dominio, o a una bandeja, abre `/inboxes/{id}/events` para una bandeja a la que puede llegar. Una clave solo de envío no puede abrir un flujo.
- Un agente (una clave restringida a una bandeja, o una conexión MCP) nunca recibe `inbox.email.quarantined`, ni en directo ni reproducido, porque nunca lee correo retenido; nombrarlo en `types` es un `403 restricted_api_key`.
- Un flujo se cierra en pocos segundos cuando se revoca su clave, la persona que creó la clave deja el equipo, o su bandeja se elimina o caduca.
- Cada clave puede mantener 5 flujos a la vez en cada proceso de la API y cada equipo 25; uno más responde `429 too_many_streams` con `retry-after`. Un solo flujo para todo el equipo basta para la mayoría de los agentes.

`wait` en `/emails/receiving` y `codes/latest` se despierta con los mismos eventos, así que esperar no cuesta nada mientras no llega correo.

## Claves de API restringidas a una bandeja

Dale a cada agente una clave que llegue solo a su propia bandeja. Consulta [Claves de API](/docs/es/api-keys).

```sh
curl -X POST "https://api.billionsend.com/api-keys" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "orders agent",
    "permission": "full_access",
    "inbox_id": "7eeb9517-aed7-40d7-ad65-500be42ed147"
  }'
```

- Requiere `permission: "full_access"` y no puede llevar también un `domain_id`. Una bandeja tiene 5 claves activas como máximo, fuera del límite de 25 del equipo.
- La clave lee su bandeja (hilos, emails, borradores, etiquetas, códigos, el flujo de eventos y `/emails/receiving` limitado a esa bandeja), responde, reenvía, escribe borradores y los envía, envía email nuevo desde su bandeja, y envía solo desde la dirección de la bandeja (`403 restricted_api_key` para otro `from`; `550 5.7.1` por SMTP).
- Todo lo demás responde `403 restricted_api_key`: no puede cambiar los ajustes de seguridad, listar ni liberar la cuarentena, aprobar borradores, crear claves ni llegar a otra bandeja.
- Deja de funcionar cuando caduca su bandeja, y eliminar la bandeja la revoca.

En el panel, los propietarios, administradores y desarrolladores eligen la bandeja en **Restringir a una bandeja de entrada** al crear una clave.

## Webhooks

Los eventos de bandeja (`inbox.created`, `inbox.thread.created`, `inbox.email.received`, `inbox.email.sent`, `inbox.email.quarantined`, `inbox.expired`, los eventos `inbox.draft.*` y más) van solo a los endpoints que los nombran, nunca a un endpoint suscrito a todos los eventos. Un endpoint se puede limitar a algunas bandejas con `inbox_ids`. `email.received` se sigue disparando para el correo de bandeja una vez entregado. Cargas: [Webhooks](/docs/es/concepts/webhooks).

## Actividad

Todo lo que se hace en una bandeja queda registrado: envíos y decisiones de las reglas, rechazos, borradores, aprobaciones, liberaciones, lecturas de códigos, cambios de seguridad, eliminaciones y claves. La pestaña **Actividad** de la bandeja lo lista con quién actuó: una persona, una clave de API o una app conectada. Las decisiones guardan solo códigos de motivo, nunca contenido, códigos ni direcciones.

## Límites

| Límite | Valor |
| --- | --- |
| Bandejas de entrada | 3 en Free, 25 en Starter, ilimitadas en Pro y Scale. |
| Bandejas creadas por hora | 10 en Free, 60 en Starter, 600 en Pro y Scale. |
| Correo por bandeja | 200 mensajes aceptados por hora móvil para una bandeja de agente, 2000 para una bandeja de personas. Superado, los remitentes reciben `452 4.2.2` y lo reintentan más tarde. |
| Envíos | `send_cap` destinatarios por día UTC. Una bandeja nueva llega a destinatarios nuevos poco a poco: 10 el primer día de envío, luego 20, 40, 80, 160 y así hasta el tope. |
| Destinatarios por envío | 50 (`to`, `cc` y `bcc` juntos); 10 desde una dirección compartida. |
| Adjuntos por envío | 10 MiB decodificados en total; ninguno desde una dirección compartida. |
| Dominio compartido | 1000 destinatarios por día UTC para todas las direcciones compartidas de tu equipo; una bandeja compartida sin usar en 90 días se elimina. |
| Etiquetas | 100 por bandeja. |
| Listas de seguridad | 500 entradas de lista de permitidos, 50 direcciones propietarias, 5 direcciones `forward_to`. |
| Claves restringidas a una bandeja | 5 activas por bandeja. |
| Revisión (screening) | 200 mensajes por bandeja por día; superado, el correo que necesita revisión se pone en cuarentena. |
| Espera | 50 segundos por petición; 20 esperas a la vez por equipo en cada proceso de la API. |
| Flujos de eventos | 5 por clave de API y 25 por equipo a la vez en cada proceso de la API; los eventos se reproducen durante 24 horas. |
| Borradores y papelera | Un borrador pendiente caduca a los 7 días; un hilo en la papelera se elimina a los 30. |
| Retención | El correo de bandeja sigue la retención del correo recibido: 30 días. |

Las bandejas de entrada en sí no cuestan nada: el correo recibido cuenta una vez por mensaje contra tu límite de recepción, nunca contra tu volumen de envío, como se explica en [Recepción](/docs/es/receiving).

## Panel

**Bandejas de entrada** en la barra lateral lista tus bandejas en las pestañas **Todas**, **Agente** y **Personas**, con lo que requiere atención: borradores por aprobar, hilos sin leer y mensajes en cuarentena. Una fila fija **Todo lo recibido** abre todos los emails que recibieron tus dominios. La página de una bandeja tiene cuatro pestañas: **Conversaciones** (leer, responder y aprobar borradores en el sitio), **Pendientes de revisión** (borradores y cuarentena), **Seguridad y reglas** y **Actividad**.

Cualquier miembro puede trabajar los hilos de una bandeja, aprobar borradores y liberar la cuarentena. Los propietarios, administradores y desarrolladores pueden además crear, cambiar y eliminar bandejas, cambiar las reglas de seguridad, crear claves restringidas a una bandeja, eliminar correo recibido y activar catch-all. Consulta los [roles del equipo](/docs/es/team-roles).

## MCP

Los [clientes MCP](/docs/es/mcp) trabajan con bandejas bajo tres permisos: `receiving:read` (leer correo, esperarlo, leer códigos, listar bandejas, hilos, etiquetas y borradores, buscar hilos, leer reglas de seguridad), `receiving:reply` (responder, reenviar, enviar desde una bandeja, escribir, enviar y eliminar borradores, organizar hilos y etiquetas) y `receiving:manage` (crear, cambiar y eliminar bandejas, listar y liberar la cuarentena). Un cliente MCP ve siempre el correo como lo ve un agente: sin correo retenido y con el texto de los mensajes delimitado como no fiable. Nunca aprueba borradores, y `create_inbox` admite `accept_from` y ningún otro ajuste de seguridad; nunca cambia las reglas de seguridad de una bandeja.

## Notas sobre la API

- Crear una bandeja o un borrador responde con el objeto completo.
- `email_address` es opcional: si se omite, la bandeja recibe una dirección permanente aleatoria en el dominio compartido.
- `kind` vale `agent` por defecto, así que una bandeja creada sin él tiene las protecciones de un agente.
- No hay agente alojado: `GET /inboxes/{id}/agent` responde `instructions`, `tone` y `actions` vacíos, y `PATCH /inboxes/{id}/agent` responde `422`.
- No se admiten: `headers` personalizadas en respuestas, reenvíos y envíos de borradores, ni adjuntos con `path` (URL remota). Cada uno responde `422` salvo que su valor esté vacío.
- Una respuesta, un reenvío o un envío de borrador retenido por las reglas de la bandeja responde `202` con el borrador en lugar de `200` con el email: comprueba que `object` valga `inbox_draft` antes de tratar el resultado como enviado.
- Errores de bandeja: `403 inbox_send_policy`, `429 inbox_send_cap_reached`, `403 approval_required`, `403 email_quarantined` y `503 name_review_unavailable` (consulta [Errores](/docs/es/api-reference/basics)).
- Los eventos de webhook `inbox.*` son opcionales; `inbox.thread.assigned` e `inbox.thread.unassigned` no se envían.
