Recepción
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.
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.
Hay dos formas de elegir qué direcciones aceptan correo: crea una bandeja de entrada para una dirección, o activa catch-all para aceptar todas las demás direcciones del dominio.
Configuración
-
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 deexample.comsiguen con tu proveedor actual. -
Añade y verifica ese nombre exacto en Dominios, igual que para el envío. Verificar
example.comno cubre sus subdominios. -
Activa la recepción: abre el dominio y enciende Activar la recepción, o llama a la API:
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. -
Publica los dos registros MX que aparecen en los registros del dominio, en tu proveedor de DNS:
Tipo Nombre Valor Prioridad MX inbound.example.commx1.billionsend-dns.com10MX inbound.example.commx2.billionsend-dns.com10Cada 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.
-
Elige las direcciones: crea una bandeja de entrada 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.
-
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 del dominio y sus variantes con
+tag:orders+4821@llega a la bandeja deorders@. - Con catch-all activado, también todas las demás direcciones:
support@,invoices@,reply+ticket-4821@. Leereceived_foren 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_forlista las direcciones de tus dominios a las que el mensaje se entregó de verdad, con copia oculta incluida.toyccson solo lo que dicen las cabeceras, así que enruta porreceived_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.comse 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,headersyrawvalennull,attachmentsqueda 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, o HTTP directo. Estos endpoints requieren una clave de API 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.
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. |
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:
curl "https://api.billionsend.com/emails/receiving?inbox_id=7eeb9517-aed7-40d7-ad65-500be42ed147&from=example.org&wait=30" \
-H "Authorization: Bearer bs_..."
- Sin
beforenisince, 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), 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 se construye con estos resultados.
Spam, virus y confianza
spam_verdict:pass,gray(spam_scorede 25 a 49) ofail(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(convirus_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) onullcuando no se hizo ningún análisis. El email infectado queda retenido: no disparaemail.receivedhasta que una persona lo libera en el panel, y sus descargas responden410 email_blocked, incluso después de liberarlo.screening.sender_trust: hasta qué punto está demostrado el remitente. Consulta Seguridad del agente.
Contenido
html_format:data_uri(por defecto) incrusta las imágenes en línea en el HTML;?html_format=cidmantiene las referenciascid:para emparejarlas con elcontent_idde cada adjunto.textllega sin caracteres invisibles;htmlllega exactamente como se recibió.extracted_textes la parte de respuesta del mensaje, limpia de texto que una persona no ve.extractedincluye uncodede verificación o unlinkde 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:pendinghasta que se lee el archivo;okcontext;unsupportedpara otros archivos (.docy.xlsantiguos, PowerPoint, imágenes);encryptedpara un archivo protegido con contraseña;too_largepor encima de 25 MB, o cuando leerlo requeriría más memoria de la permitida;unreadablepara un archivo dañado;timeoutofailedcuando la lectura no terminó.nullpara el correo recibido antes de que se leyera el texto de los adjuntos.flags:truncatedcuando un límite cortó el texto (100.000 caracteres, las primeras 500 páginas de un PDF),hidden_textcuando 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 hojapor 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:
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
textohtml,subject,cc,bccyreply_all. Va alReply-Todel mensaje o, si no hay, a su remitente. - Reenviar admite
to,cc,bcc, una nota,subjectymode:inline(por defecto) cita el original,attachmentlo adjunta comoforwarded_message.eml. fromes 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: trueretiene 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.
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.
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 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 añade cuarentena, revisión y reglas de envío por encima.