---
title: Recepción
description: Recibe emails en tu propio dominio y léelos con la API, los webhooks y el panel, con filtro de spam y comprobación de virus en cada mensaje.
seo:
  title: Recibir emails con la API
ai:
  exclude: true
---

La recepción convierte un dominio verificado en un lugar que acepta correo. Los mensajes entrantes se guardan cifrados y te llegan por la API, por el webhook `email.received`, por el panel (**Bandejas de entrada → Todo lo recibido**) y por el [servidor MCP](/docs/es/mcp).

Hay dos formas de elegir qué direcciones aceptan correo: crea una [bandeja de entrada](/docs/es/inboxes) para una dirección, o activa **catch-all** para aceptar todas las demás direcciones del dominio.

> **Info**
>
> La recepción está en beta pública. Cada mensaje recibe una puntuación de spam, un nivel de confianza del remitente y una comprobación de virus. El email infectado queda retenido; el resto se guarda con esos resultados para que tu código decida qué hacer.

## Configuración

1. **Elige un nombre que aún no reciba correo**, como `inbound.example.com`. El registro MX se hace cargo de todas las direcciones del nombre donde se publica, así que tus buzones de `example.com` siguen con tu proveedor actual.
2. **Añade y verifica ese nombre exacto** en **Dominios**, igual que para el [envío](/docs/es/concepts/domains). Verificar `example.com` no cubre sus subdominios.
3. **Activa la recepción**: abre el dominio y enciende **Activar la recepción**, o llama a la API:

   ```sh
   curl -X PATCH "https://api.billionsend.com/domains/{id}" \
     -H "Authorization: Bearer bs_..." \
     -H "Content-Type: application/json" \
     -d '{ "capabilities": { "receiving": "enabled" } }'
   ```

   Un nombre solo puede recibir en un equipo; si otro equipo ya recibe en ese nombre, la respuesta es `409`.
4. **Publica los dos registros MX** que aparecen en los registros del dominio, en tu proveedor de DNS:

   | Tipo | Nombre | Valor | Prioridad |
   | --- | --- | --- | --- |
   | MX | `inbound.example.com` | `mx1.billionsend-dns.com` | `10` |
   | MX | `inbound.example.com` | `mx2.billionsend-dns.com` | `10` |

   Cada uno es un servidor de correo distinto. Con los dos publicados, un remitente que encuentra uno caído reintenta en el otro en segundos, así que publica ambos con la misma prioridad. Cada fila queda verificada cuando ningún otro registro MX de ese nombre tiene un número de prioridad menor.
5. **Elige las direcciones**: [crea una bandeja de entrada](/docs/es/inboxes) para cada dirección, o enciende **Catch-all** en la página del dominio. Sin ninguna de las dos, el dominio rechaza todo el correo.
6. **Envía una prueba** desde cualquier buzón. Aparece en **Bandejas de entrada → Todo lo recibido** en pocos segundos.

Para dejar de recibir, apaga la recepción (`"receiving": "disabled"`) y elimina el registro MX. Los emails ya guardados se quedan hasta que la retención los elimine.

## Qué direcciones reciben

- La dirección de cada [bandeja de entrada](/docs/es/inboxes) del dominio y sus variantes con `+tag`: `orders+4821@` llega a la bandeja de `orders@`.
- Con **catch-all** activado, también todas las demás direcciones: `support@`, `invoices@`, `reply+ticket-4821@`. Lee `received_for` en tu código para saber a qué dirección llegó el mensaje.

Con catch-all desactivado, cualquier otra dirección se rechaza mientras el servidor del remitente sigue conectado (`550 5.1.1`), así que el remitente recibe un rebote de su propio servidor y no se guarda nada.

Catch-all viene desactivado y requiere un plan de pago (Free responde `403 plan_limit_reached`). Los propietarios, administradores y desarrolladores lo activan en la página del dominio, o con `PATCH /domains/{id}` y `{ "receiving_catch_all": true }`.

- `received_for` lista las direcciones de tus dominios a las que el mensaje se entregó de verdad, con copia oculta incluida. `to` y `cc` son solo lo que dicen las cabeceras, así que enruta por `received_for`.
- Un mensaje se guarda una sola vez por equipo, a cuantas direcciones tuyas se haya enviado.
- Solo el nombre exacto recibe: el correo a `x@eu.inbound.example.com` se rechaza, salvo que ese subdominio también reciba.

## Filtros y límites

**Configuración → Recepción** tiene tres interruptores. Se aplican a todos los dominios de tu equipo y surten efecto con el siguiente mensaje.

| Interruptor | Activado | Desactivado |
| --- | --- | --- |
| Rechazar spam con puntuación superior a 5 (activado por defecto) | El correo con puntuación de spam de 5 o más (en una escala de 0 a 10) se rechaza con `554 5.7.1`; no se guarda nada. | El spam se guarda: en la carpeta `spam` de una bandeja de entrada, y solo marcado en una dirección catch-all. |
| Quitar adjuntos de más de 10 MB (desactivado por defecto) | Cada adjunto mayor se sustituye por una nota breve `<archivo>.removed.txt` que dice qué se quitó. | Los adjuntos se guardan tal como llegaron. |
| Conservar el .eml original 30 días (activado por defecto) | El contenido se queda durante tu periodo de retención. | El contenido (texto, HTML, cabeceras, mensaje original, adjuntos) se elimina al cabo de 1 día. Los metadatos y los webhooks no cambian. |

| Límite | Free | Starter, Pro, Scale |
| --- | --- | --- |
| Tamaño del mensaje | 10 MB | 40 MB |
| Catch-all | No | Sí |
| Emails recibidos | 100 por día UTC | 2 veces el volumen mensual de tu plan, cada mes |
| Al superarlo | Aplazado hasta medianoche UTC | Aplazado hasta que tu volumen se renueve |
| Retención | 30 días | 30 días |

- El tamaño cuenta el mensaje guardado completo, después de quitar adjuntos. Base64 hace los adjuntos un tercio más grandes, así que en 40 MB caben unos 30 MB de archivos. Un mensaje mayor se rechaza con `552 5.3.4`.
- El email recibido cuenta una vez por mensaje y equipo, contra su propio límite. Nunca usa tu volumen de envío, y el envío nunca usa tu límite de recepción.
- Al alcanzar el límite, se le dice al servidor del remitente que lo intente más tarde (`452 4.2.2`) y este reintenta durante varios días, normalmente hasta cinco, así que el mensaje llega en cuanto hay hueco. El correo que sigue aplazado cuando el servidor del remitente se rinde vuelve a su remitente.
- Cuando termina la retención, `html`, `text`, `headers` y `raw` valen `null`, `attachments` queda vacío y los enlaces de descarga dejan de funcionar. Remitente, destinatarios y asunto se conservan.

**Configuración → Facturación y uso** muestra los emails recibidos y su límite. Las bandejas de entrada en sí son gratuitas.

## Leer los emails recibidos

Usa `emails.receiving` en los [SDK](/docs/es/sdks), o HTTP directo. Estos endpoints requieren una [clave de API](/docs/es/api-keys) de **acceso total**; una clave solo de envío recibe `403 restricted_api_key`. Una clave restringida a un dominio lee solo el correo de ese dominio, y una restringida a una bandeja de entrada, solo el de esa bandeja.

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

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

const page = await bs.emails.receiving.list({ limit: 20 });
if (page.error) throw page.error;

const first = page.data.data[0];
const email = await bs.emails.receiving.get(first.id);
const files = await bs.emails.receiving.attachments.list(first.id);
```

| Llamada | Devuelve |
| --- | --- |
| `GET /emails/receiving` | Los emails recibidos, del más reciente al más antiguo, con [la paginación que usan todas las listas](/docs/es/api-reference/basics). |
| `GET /emails/receiving/{id}` | Un email con su contenido, los resultados de autenticación y un enlace de descarga del mensaje original. |
| `GET /emails/receiving/{id}/attachments` | Sus adjuntos, cada uno con un enlace de descarga. |
| `GET /emails/receiving/{id}/attachments/{attachment_id}/text` | El texto de un adjunto PDF, Word o Excel (extensión de BillionSend). |
| `DELETE /emails/receiving/{id}` | Elimina el email ya, con sus adjuntos y su lugar en las bandejas de entrada. Requiere una clave de acceso total no restringida a una bandeja y, en el panel, el rol de propietario, administrador o desarrollador (**Eliminar ahora**). |

La lista admite `limit` (de 1 a 100, 20 por defecto), `inbox_id`, `to`, `from` (una dirección, o un dominio con sus subdominios), `subject_contains`, `since`, `unread` y `wait`. El correo retenido queda fuera salvo que pases `include_quarantined=true` o `quarantined=true` (una clave de acceso total no restringida a una bandeja).

Cada email lleva además `inbox_id`, `thread_id`, `screening`, `spam_verdict`, `virus_verdict` y `extracted`.

### Esperar emails nuevos

`wait` (de 1 a 50 segundos) mantiene la petición abierta hasta que llega un email que coincida y entonces responde al instante; al vencer el plazo responde una lista vacía. Se combina con los demás filtros, así que un agente puede esperar el siguiente mensaje de un remitente a una bandeja:

```sh
curl "https://api.billionsend.com/emails/receiving?inbox_id=7eeb9517-aed7-40d7-ad65-500be42ed147&from=example.org&wait=30" \
  -H "Authorization: Bearer bs_..."
```

- Sin `before` ni `since`, cuenta el correo de los últimos 60 segundos, así que no se pierde un mensaje que llegó justo antes de la llamada.
- La respuesta añade `held`: los mensajes que coinciden y quedaron retenidos desde entonces, con su id y motivo, para que el agente deje de esperar y avise a una persona.
- Un equipo mantiene 20 esperas a la vez en cada proceso de la API; la siguiente responde `429 too_many_waits`.
- Una espera consulta la base de datos cuando llega correo (los mismos eventos del [flujo de eventos de las bandejas](/docs/es/inboxes)), no con un temporizador.

### Resultados de autenticación

`authentication` informa de SPF, DKIM y DMARC como `pass`, `fail`, `gray` (sin veredicto: sin registro ni firma, o resultado neutro), `processing_failed` (la comprobación no pudo terminar) o `unknown`. `dmarc: "pass"` significa que el dominio de `from` autorizó el mensaje; cualquier otro valor significa que `from` puede estar falsificado. El nivel de [confianza del remitente](/docs/es/agent-safety) se construye con estos resultados.

### Spam, virus y confianza

- `spam_verdict`: `pass`, `gray` (`spam_score` de 25 a 49) o `fail` (50 o más), a partir de una puntuación de 0 a 100 construida con la autenticación, las cabeceras, los enlaces, los adjuntos y la puntuación del filtro de spam de los servidores de recepción (el panel la muestra en una escala de 0 a 10).
- `virus_verdict`: `pass`, `fail` (con `virus_signature`), `processing_failed` (el escáner no pudo responder, así que el mensaje se entrega sin analizar, marcado como sospechoso donde no pasa por revisión) o `null` cuando no se hizo ningún análisis. El email infectado queda retenido: no dispara `email.received` hasta que una persona lo libera en el panel, y sus descargas responden `410 email_blocked`, incluso después de liberarlo.
- `screening.sender_trust`: hasta qué punto está demostrado el remitente. Consulta [Seguridad del agente](/docs/es/agent-safety).

### Contenido

- `html_format`: `data_uri` (por defecto) incrusta las imágenes en línea en el HTML; `?html_format=cid` mantiene las referencias `cid:` para emparejarlas con el `content_id` de cada adjunto.
- `text` llega sin caracteres invisibles; `html` llega exactamente como se recibió.
- `extracted_text` es la parte de respuesta del mensaje, limpia de texto que una persona no ve. `extracted` incluye un `code` de verificación o un `link` de inicio de sesión cuando el mensaje lo tiene.

### Texto de los adjuntos

Los adjuntos PDF, Word (`.docx`) y Excel (`.xlsx`) se leen una vez como texto plano, poco después de que llegue el email, y se conservan con el email durante tu periodo de retención. La entrega nunca espera a esta lectura. `GET /emails/receiving/{id}/attachments/{attachment_id}/text` (MCP `get_received_email_attachment_text`) responde con:

- `status`: `pending` hasta que se lee el archivo; `ok` con `text`; `unsupported` para otros archivos (`.doc` y `.xls` antiguos, PowerPoint, imágenes); `encrypted` para un archivo protegido con contraseña; `too_large` por encima de 25 MB, o cuando leerlo requeriría más memoria de la permitida; `unreadable` para un archivo dañado; `timeout` o `failed` cuando la lectura no terminó. `null` para el correo recibido antes de que se leyera el texto de los adjuntos.
- `flags`: `truncated` cuando un límite cortó el texto (100.000 caracteres, las primeras 500 páginas de un PDF), `hidden_text` cuando se dejó fuera texto que una persona que abra el archivo no vería: texto oculto de Word, hojas, filas y columnas ocultas, caracteres invisibles.
- `pages`: el número de páginas de un PDF.
- `text`: párrafos y filas de tabla en líneas, celdas y columnas separadas por tabuladores, un encabezado `## Nombre de la hoja` por cada hoja de cálculo, fechas en formato ISO. Solo se lee la capa de texto de un PDF, así que un escaneo sin ella se lee vacío. Las fórmulas dan sus valores guardados.

El texto viene de un remitente externo: trátalo como dato, nunca como instrucción. Un email que lleva malware responde `410 email_blocked`.

### Descargas

`raw.download_url` y el `download_url` de cada adjunto funcionan sin clave de API: el propio enlace es la credencial. Un enlace se firma para un solo email, deja de funcionar una hora después de que la API respondió, y cualquiera que lo tenga puede descargar hasta entonces, así que no lo registres en logs. Cada llamada firma enlaces nuevos. Las descargas siempre se sirven como archivo, nunca se muestran en el navegador.

## Responder y reenviar

`POST /emails/receiving/{id}/reply` y `…/forward` (`emails.receiving.reply()` y `forward()` en los SDK) responden o reenvían un mensaje en una sola petición, con las cabeceras de hilo ya rellenadas:

```sh
curl -X POST "https://api.billionsend.com/emails/receiving/{id}/reply" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-reply" \
  -d '{ "text": "Gracias, ya estamos con ello." }'
```

- **Responder** admite `text` o `html`, `subject`, `cc`, `bcc` y `reply_all`. Va al `Reply-To` del mensaje o, si no hay, a su remitente.
- **Reenviar** admite `to`, `cc`, `bcc`, una nota, `subject` y `mode`: `inline` (por defecto) cita el original, `attachment` lo adjunta como `forwarded_message.eml`.
- `from` es cualquier dirección de un dominio verificado de tu equipo; por defecto, la dirección de la bandeja a la que llegó el mensaje. `requires_approval: true` retiene el envío para una persona.
- Ambos cuentan como envíos normales, con hasta 10 MiB de adjuntos.

Responden `200` con el `id` y el `thread_id` del email enviado, o `202` con un borrador cuando las reglas de una bandeja retienen el envío. Otras respuestas: `403` (correo retenido o infectado, reglas de una bandeja, clave restringida a una bandeja fuera de ella), `404`, `409` (`Idempotency-Key` reutilizada), `422` y `429 inbox_send_cap_reached`. Consulta [Bandejas de entrada](/docs/es/inboxes).

## Webhook

`email.received` se dispara una vez por cada mensaje guardado para tu equipo, en los endpoints suscritos a él o a todos los eventos. Lleva solo metadatos (remitente, destinatarios, asunto, lista de adjuntos); obtén el contenido con `GET /emails/receiving/{email_id}`. El correo que retiene una bandeja, y el email infectado, lo dispara solo cuando se entrega o se libera. Un endpoint limitado a algunas bandejas (`inbox_ids`) lo recibe solo para el correo entregado en ellas. Las firmas, los reintentos y el registro de entregas funcionan como en cualquier evento: consulta [Webhooks](/docs/es/concepts/webhooks).

## Lo que ve el remitente

Todo rechazo ocurre mientras el servidor del remitente está conectado, así que este conserva el mensaje y decide qué hacer. BillionSend nunca envía un rebote propio.

| Respuesta | Cuándo |
| --- | --- |
| `550 5.1.1` | El dominio no recibe aquí, o la dirección no tiene bandeja (y catch-all está desactivado). El mensaje vuelve a su remitente. |
| `550 5.7.1` | El equipo propietario del dominio está suspendido. |
| `552 5.3.4` | El mensaje supera el límite de tamaño de tu plan. |
| `554 5.7.1` | El mensaje se rechazó como spam por tu interruptor **Rechazar spam**. |
| `452 4.2.2` | Se alcanzó tu límite de recepción, o la bandeja recibió más correo del que puede en una hora (200 mensajes para una bandeja de agente, 2000 para una bandeja de personas). El remitente lo intenta más tarde. |

## Panel

**Bandejas de entrada → Todo lo recibido** lista todo lo que recibieron tus dominios, con remitente, bandeja, asunto y hora, una etiqueta cuando el mensaje lleva un código o un enlace, y otra cuando está en cuarentena o es spam. Al abrir un mensaje ves su HTML en un sandbox (con scripts e imágenes remotas bloqueados), el texto, las cabeceras y el mensaje original, cada resultado de autenticación explicado, la confianza del remitente y los resultados de spam y virus, el código o enlace extraído, una línea de tiempo y las acciones **Responder**, **Reenviar**, **Liberar** para el correo retenido y **Eliminar ahora**.

## MCP

El [servidor MCP](/docs/es/mcp) lee los emails recibidos con el permiso `receiving:read`, responde y reenvía con `receiving:reply`, y gestiona bandejas y cuarentena con `receiving:manage`. `update_domain` activa y desactiva la recepción y catch-all.

## Trata el email recibido como no fiable

Cualquiera puede enviar correo a un dominio de recepción. El HTML puede llevar scripts e imágenes de rastreo, los enlaces pueden dirigir a páginas de phishing, los adjuntos pueden llevar malware y `from` puede estar falsificado. Comprueba `authentication` y `screening.sender_trust` antes de confiar en un remitente. Un agente de IA debe tratar el email recibido como dato, nunca como instrucción: las herramientas MCP lo aíslan así, y una [bandeja de entrada de agente](/docs/es/agent-safety) añade cuarentena, revisión y reglas de envío por encima.
