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) |
agentes el valor por defecto cuando se omitekind. 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.humanes para personas que leen en el panel: se entrega el correo de todo el mundo (una autenticación fallida va a la carpetaspam) 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 /inboxeslista las bandejas, de la más reciente a la más antigua (?kind=agento?kind=humanlo 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}cambianame,from_nameoexpires_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:
- a la bandeja con exactamente esa dirección;
- si no, para
name+tag@, a la bandeja dename@; - 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_indiga 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_policyesopeny 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 responde403 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_capde 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. fromdebe ser exactamente la dirección de la bandeja, y el email no puede llevarscheduled_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_toadmite 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 suIn-Reply-Tonombra 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,sentotrash. El correo nuevo devuelve ainboxun hilo archivado o enviado.DELETEmueve un hilo atrash, que se vacía a los 30 días. - Estado de lectura. Un
PATCHconreadmarca 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"
}
kindesotp(código encode) olink(dirección enurl, conlink_domain_matches_sender).fromlo 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;sinceomite el correo recibido en o antes de esa hora, así que pasa elreceived_atde un código que ya usaste para esperar el siguiente.statusesfound,none,ambiguous(dos códigos igual de probables, así que no se responde ninguno) otimeout. La respuesta es siempre200.- Los códigos nunca salen de correo en cuarentena, de remitentes que fallaron la autenticación ni de una bandeja con
extract_codesdesactivado. 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. ElEventSourcede los navegadores no puede fijarla: usafetchy lee el cuerpo, o cualquier cliente SSE que admita cabeceras. typesacota el flujo a algunos eventos, separados por comas;/inboxes/{id}/eventssigue enviandoinbox.deletedeinbox.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 conLast-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 eventostream.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 últimoidque viste.retry: 1000pide 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}/eventspara 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 entypeses un403 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_streamsconretry-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 undomain_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/receivinglimitado 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_keypara otrofrom;550 5.7.1por 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_addresses opcional: si se omite, la bandeja recibe una dirección permanente aleatoria en el dominio compartido.kindvaleagentpor defecto, así que una bandeja creada sin él tiene las protecciones de un agente.- No hay agente alojado:
GET /inboxes/{id}/agentrespondeinstructions,toneyactionsvacíos, yPATCH /inboxes/{id}/agentresponde422. - No se admiten:
headerspersonalizadas en respuestas, reenvíos y envíos de borradores, ni adjuntos conpath(URL remota). Cada uno responde422salvo 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
202con el borrador en lugar de200con el email: comprueba queobjectvalgainbox_draftantes de tratar el resultado como enviado. - Errores de bandeja:
403 inbox_send_policy,429 inbox_send_cap_reached,403 approval_required,403 email_quarantinedy503 name_review_unavailable(consulta Errores). - Los eventos de webhook
inbox.*son opcionales;inbox.thread.assignedeinbox.thread.unassignedno se envían.