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

Bandejas de entrada

Direcciones de email que guardan el correo en hilos y responden desde la misma dirección, para un agente de IA o para personas.

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, o a personas, que la leen en el panel. Una bandeja es una dirección en uno de tus dominios de recepción, o una dirección en el dominio compartido de BillionSend, que no necesita DNS.

Los SDK cubren todos los endpoints de bandejas como inboxes.*, incluidas las reglas de seguridad, la cuarentena, las aprobaciones y el flujo de eventos en directo.

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

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:

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

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.

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

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.

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:

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

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:

curl "https://api.billionsend.com/inboxes/{id}/codes/latest?from=example.org&wait=30" \
  -H "Authorization: Bearer bs_..."
{
  "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.

curl -N "https://api.billionsend.com/inboxes/events?types=inbox.email.received" \
  -H "Authorization: Bearer bs_..." \
  -H "Accept: text/event-stream"
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.
  • 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.

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.

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.

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.

MCP

Los clientes 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).
  • Los eventos de webhook inbox.* son opcionales; inbox.thread.assigned e inbox.thread.unassigned no se envían.

¿Te ha resultado útil esta página?