Saltar al contenido
Esc
↑↓navegar↵abrir⌘Jvista previa
En esta página

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

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

    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 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 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, 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 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), 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_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.

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:

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.

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.

¿Te ha resultado útil esta página?