Documentación de la API beta

Crea flujos de trabajo de correo de agentes con dominio verificado.

Esta documentación beta cubre la verificación del correo del propietario, la autenticación de la API, la configuración de skills de agentes, el onboarding de dominios personalizados, los buzones de agentes, el envío, los webhooks entrantes, los eventos de entrega, los límites de tasa y los controles de entrega.

Inicio

Primeros pasos

La beta personal de LoftBox comienza con un único correo de propietario. El registro crea la organización y envía por correo un token de verificación de 6 dígitos. Solo tras la verificación del correo del propietario, LoftBox devuelve la primera clave de API, y esa clave en texto plano se muestra una sola vez. La verificación también envía al propietario un correo de bienvenida con los límites de la beta y la futura vía de registro de administración/facturación.

Las cuentas de la beta personal están limitadas a 100 envíos salientes por día. La retención de mensajes del buzón es de 7 días por defecto. El onboarding empresarial, la facturación, la membresía de la organización y límites mayores son elementos del roadmap.

  • POST /v1/auth/signupCrea una organización de beta personal y envía el token de verificación del correo del propietario.
  • POST /v1/auth/signup/verifyVerifica el correo del propietario, recibe la clave de API inicial una sola vez y activa el aviso de bienvenida del propietario.
  • POST /v1/agentsCrea una identidad de agente con propietario, propósito y alcance de política.
  • POST /v1/domainsInicia el onboarding de dominio personalizado para un dominio que controlas.
  • POST /v1/agents/{agent_id}/mailboxesCrea un buzón beta gestionado por LoftBox o un buzón de dominio personalizado verificado.
  • POST /v1/messagesEnvía correo operativo desde el buzón del agente.
  • GET /v1/mailboxes/{id}/inboxSondea los mensajes entrantes sin confirmar cuando el agente no tiene un endpoint de webhook.
Endpoint

URL base y documentación legible por máquina

El endpoint público canónico de la API es https://api.loftbox.net. La página de inicio mantiene una /api/* ruta de proxy para la verificación de vista previa, pero las integraciones de producción deben usar el nombre de host de la API dedicado.

export BASE_URL="https://api.loftbox.net"
export LOFTBOX_API_KEY="lb_live_replace_me"

Comprueba el edge y el esquema antes de conectar una integración:

curl -i "$BASE_URL/health"
curl -i "$BASE_URL/openapi.json"
curl -i "$BASE_URL/llms.txt"

La https://loftbox.net/api ruta elimina el prefijo /api y lo reenvía al mismo origen de la API de Fly. Úsala para comprobaciones de vista previa de Pages, no como URL de integración principal.

Autenticación

Autenticación de la API

Comienza registrando el correo del propietario para la organización de beta personal. El propietario recibe un token de verificación por correo; la llamada de verificación devuelve la clave de API inicial una sola vez y envía el aviso de bienvenida del propietario.

export LOFTBOX_OWNER_EMAIL="[email protected]"

curl -i -X POST "$BASE_URL/v1/auth/signup" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "'"$LOFTBOX_OWNER_EMAIL"'",
    "organization_name": "Example Agents",
    "slug": "example-agents"
  }'

export LOFTBOX_VERIFICATION_TOKEN="123456"

curl -i -X POST "$BASE_URL/v1/auth/signup/verify" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "'"$LOFTBOX_OWNER_EMAIL"'",
    "verification_token": "'"$LOFTBOX_VERIFICATION_TOKEN"'"
  }'

Usa la clave de API del lado del servidor devuelta con el encabezado Authorization . Nunca expongas las claves de API en navegadores, clientes móviles, registros públicos o eventos de analítica.

curl -i "$BASE_URL/v1/agents" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

Almacena las claves en un almacenamiento de secretos del lado del servidor como Fly secrets, variables de entorno gestionadas por la plataforma de despliegue o un gestor de secretos dedicado. No pegues claves reales en comentarios de issues, capturas de pantalla, herramientas de analítica o código de navegador.

Rota las claves cuando un operador se va, un secreto puede haberse filtrado o un entorno ya no necesita acceso a la API.

Configuración del agente

Instalación de una línea y prompt del agente

Los agentes pueden instalar las skills de correo públicas de LoftBox y luego ejecutar el flujo de onboarding solo con el correo del propietario. La skill de registro deriva la etiqueta de la organización, un external_idestable, el slug del agente y la parte local del buzón a partir del agente actual. Tras el registro, las skills de envío y de comprobación de bandeja de entrada instaladas usan la clave de API emitida y el ID del buzón.

curl -fsSL https://loftbox.net/install.sh | sh
curl -fsSL https://loftbox.net/install.sh | sh -s -- --agent codex
curl -fsSL https://loftbox.net/install.sh | sh -s -- --agent claude
curl -fsSL https://loftbox.net/install.sh | sh -s -- --target "$HOME/.my-agent/skills"
If the LoftBox mail skill is missing, install it with:
curl -fsSL https://loftbox.net/install.sh | sh

Use register-loftbox-mail-agent to register this agent for LoftBox personal beta.
Ask me only for my owner email.
After registration, use send-loftbox-mail to send and check-loftbox-mail to check replies.
curl -fsSL https://loftbox.net/install.sh | sh -s -- --check
curl -fsSL https://loftbox.net/install.sh | sh -s -- --update

Usa las comprobaciones de actualización solo como vía de notificación. Instalar un nuevo paquete de skills cambia el comportamiento del agente, por lo que las actualizaciones deben ejecutarse tras la aprobación del operador.

Solo solicita otro valor si la identidad del agente no se puede derivar o un ID externo duplicado pertenece a un agente distinto.

Dominios

Onboarding de dominios personalizados

Todo dominio saliente debe verificarse antes de que los buzones puedan usarlo. La API devuelve los registros DNS necesarios para la propiedad, el enrutamiento entrante, la alineación del remitente y la verificación de entrega.

  1. Crea el dominio con POST /v1/domains.
  2. Obtén los registros requeridos con GET /v1/domains/{id}/dns.
  3. Añade los registros TXT, MX, DKIM y return-path devueltos en tu proveedor de DNS.
  4. Llama a POST /v1/domains/{id}/verify tras la propagación del DNS.
  5. Espera a que el estado entrante y saliente estén ambos verificados antes de crear buzones de producción.
curl -i "$BASE_URL/v1/domains" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain":"mail.example.com"}'

curl -i "$BASE_URL/v1/domains/domain_uuid/dns" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

curl -i -X POST "$BASE_URL/v1/domains/domain_uuid/verify" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

O deja que un agente dirija todo el onboarding de negocio de extremo a extremo con el flujo unificado onboard-business-domain (autenticación de correo → onboarding de dominio → DNS). Pega este prompt en tu agente:

If the LoftBox mail skill is missing, install it with:
curl -fsSL https://loftbox.net/install.sh | sh

Use onboard-business-domain to connect my business domain for verified sending.
Ask me only for my owner email and the domain to send from.

1. Email auth: register my owner email. LoftBox emails a 6-digit token — ask me
   to paste it, then verify to obtain my organization API key (LoftBox-managed
   sending is available immediately once approved).
2. Domain onboard: run add <domain> (note the returned domain id), then read
   next_actions for the exact DNS records (TXT, DKIM, return-path, inbound MX).
   Show me each record (host, type, value).
3. DNS: let me add the records at my DNS host myself, or auto-apply them with
   apply-dns --provider route53|cloudflare using my own cloud credentials from
   the environment (they stay in my environment; LoftBox never receives them).
4. The domain re-verifies asynchronously on the server after DNS propagates.
   Poll status <domain_id> until inbound and outbound are both verified, then
   report — custom-domain sending activates once verified.
Operate only on my organization. Do not fabricate DNS values; use exactly what the API returns. If onboarding cannot proceed (domain previously deleted, or in use by another org), report it and stop.

Skills oficiales &amp; código fuente

onboard-business-domain y setup-loftbox-domain son skills oficiales de LoftBox. Se publican en el repositorio público de skills y se instalan mediante https://loftbox.net/install.sh &mdash; si un agente no puede encontrarlas, su paquete instalado está desactualizado y volver a ejecutar el instalador las añade.

La skill setup-loftbox-domain se invoca ejecutando su script directamente (el instalador no crea un setup-loftbox-domain comando de shell). $SKILL_DIR es donde sea que install.sh colocó la skill &mdash; p. ej. ~/.claude/skills/setup-loftbox-domain, ~/.codex/skills/setup-loftbox-domain, o en Hermes ~/.hermes/skills/email/setup-loftbox-domain. La skill llama a la API de LoftBox &mdash; usa exactamente los valores DNS que la API devuelve, nunca los inventes:

SKILL_DIR=<path to setup-loftbox-domain>   # e.g. ~/.claude/skills/setup-loftbox-domain

python3 "$SKILL_DIR/scripts/setup_loftbox_domain.py" add <domain>
   # onboard the domain (idempotent: resolves an existing active row on 409)
python3 "$SKILL_DIR/scripts/setup_loftbox_domain.py" dns <id>
   # list the exact DNS records to set (TXT, DKIM, return-path, MX)
python3 "$SKILL_DIR/scripts/setup_loftbox_domain.py" status <id>
   # structured status: inbound/outbound flags + next_actions
python3 "$SKILL_DIR/scripts/setup_loftbox_domain.py" verify <id>
   # trigger verification after the DNS records are in place
python3 "$SKILL_DIR/scripts/setup_loftbox_domain.py" apply-dns <id> --provider route53|cloudflare [--dry-run] [--overwrite]
   # auto-apply the next_actions records using cloud credentials from your OWN
   # environment (they never leave it). With no credentials, add the records
   # manually instead — onboarding still completes.

onboard-business-domain orquesta register-loftbox-mail-agent (autenticación de correo) y setup-loftbox-domain (onboarding de dominio + DNS) de extremo a extremo. El paso del token de correo de 6 dígitos requiere un humano, por lo que no es totalmente desatendido.

Para el lanzamiento, la beta personal usa entrega gestionada por LoftBox y gestión de MX entrante gestionada por LoftBox. Los dominios personalizados se habilitan solo tras la verificación.

Buzones

Agentes y buzones

Los agentes contienen el propósito de negocio, el contexto de propiedad y el ID externo estable. Los buzones asocian una dirección y un dominio a ese agente. Mantén los nombres mostrados, los propietarios y el alcance de política lo bastante claros para la revisión del operador.

  • Usa un buzón por cada agente operativo o rol de flujo de trabajo.
  • Usa external_id para comprobaciones de duplicados y configuración idempotente del agente.
  • Usa dominios personalizados verificados para el correo saliente de producción.
  • Desactiva o retén los envíos autónomos cuando el propósito del agente no esté claro.
curl -i "$BASE_URL/v1/agents?external_id=hermes:support-agent" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"
curl -i "$BASE_URL/v1/agents" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "slug": "support-agent",
    "external_id": "hermes:support-agent",
    "description": "Handles controlled support follow-up",
    "purpose": "Reply to support conversations after policy checks",
    "owner_label": "Customer Operations",
    "policy_scope": "agent"
  }'

curl -i "$BASE_URL/v1/agents/agent_uuid/mailboxes" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "local_part": "support-agent",
    "display_name": "Support Agent",
    "retention_days": 7
  }'

Omite domain_id para el dominio de beta personal gestionado por LoftBox. Registra un webhook del agente por separado si el agente tiene un endpoint HTTPS.

En un dominio personalizado verificado puedes marcar un buzón como catch-all ("is_catch_all": true al crear o actualizar). Cualquier dirección de ese dominio sin un buzón exacto se enruta entonces a él — útil para capturar support@, sales@, o anything@tudominio con un único agente.

Saliente

Envío de mensajes

Envía mensajes operativos o transaccionales a través de la API desde un buzón verificado. LoftBox registra las referencias de entrega, el estado de entrega, las decisiones de límite de tasa y los resultados de aprobación del operador.

curl -i "$BASE_URL/v1/messages" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "mailbox_id": "mailbox_uuid",
  "to": ["[email protected]"],
  "subject": "Support follow-up",
  "body_text": "Thanks for your message. We are checking this now.",
  "metadata": { "ticket_id": "ticket_123" },
  "send_at": "2030-01-01T09:00:00Z"
}'

Pasa send_at (RFC3339, futuro) para programar la entrega, y un encabezado Idempotency-Key para deduplicar reintentos (un reenvío devuelve el mensaje original). Lista y busca mensajes enviados o recibidos con GET /v1/messages?q=<text>&label=<name>, y organiza los hilos mediante POST/DELETE /v1/messages/{id}/labels.

LoftBox no es un emisor de marketing masivo. Las listas compradas, los destinatarios extraídos por scraping y el uso de relay SMTP genérico quedan fuera de la política del MVP.

Entrante

Webhooks entrantes y sondeo

Las respuestas se almacenan como mensajes entrantes. Los agentes con un endpoint HTTPS pueden recibir eventos de webhook firmados; los agentes sin uno deben sondear la bandeja de entrada del buzón y confirmar cada mensaje procesado.

  • message.inboundUn nuevo mensaje entrante o respuesta se ha analizado, encadenado y puesto a disposición del webhook configurado.
  • message.deliveredSe informó la entrega para el destinatario.
  • message.failedLa entrega saliente falló de forma permanente o agotó la gestión de reintentos.
curl -i "$BASE_URL/v1/agents/agent_uuid/webhooks" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/loftbox",
    "event_types": [
      "message.inbound",
      "message.delivered"
    ]
  }'

El secreto del webhook se devuelve una sola vez al crear el webhook. Almacénalo de inmediato y verifica cada firma entrante antes de confiar en el contenido del evento.

curl -i "$BASE_URL/v1/mailboxes/mailbox_uuid/inbox?limit=20" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

curl -i -X POST "$BASE_URL/v1/mailboxes/mailbox_uuid/inbox/ack" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message_ids":["message_uuid_or_msg_public_id"]}'

Confirma solo después de que el agente haya procesado el mensaje de forma duradera. El sondeo de una bandeja de entrada vacía debe aplicar backoff; el sondeo activo debe usar un intervalo moderado como 30-60 segundos.

Entrante

Streaming en tiempo real (WebSocket)

Los agentes que no pueden alojar un webhook HTTPS (por ejemplo, ejecutándose detrás de NAT o un firewall) pueden suscribirse a eventos en tiempo real a través de un WebSocket. El stream transporta los mismos tipos de evento que los webhooks, con entrega de menos de un segundo y reenvío basado en cursor de los eventos perdidos mientras estaba desconectado. Requiere el scope receive .

  • GET /v1/wsActualización a WebSocket. Autentícate con Authorization: Bearer. Filtra con ?event_types= y ?agent_id=; reanuda con ?after=<cursor>.
  • GET /v1/ws/asyncapi.jsonEspecificación AsyncAPI para el stream (pública).
wscat -c "wss://api.loftbox.net/v1/ws?event_types=message.inbound" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

# frames: {"type":"ready",...} then {"type":"event","event":{...},"cursor":"..."}
# on reconnect, pass ?after=<last cursor> to replay missed events

En un frame error con código lagged o resync_required, reconéctate usando el último cursor recibido.

Control de acceso

Permisos y claves de API

Las claves de API llevan scopes. Los scopes generales (send, receive, admin) implican scopes de grano fino (message:send, message:read, domain:manage, approval:decide, keys:manage, …), de modo que las claves existentes siguen funcionando mientras puedes emitir claves hijas de mínimo privilegio para sub-agentes.

  • POST /v1/auth/keysEmite una clave hija. Los scopes solicitados deben ser un subconjunto de los del llamante (sin escalada de privilegios). Opcional expires_in_days. La clave en texto plano se devuelve una sola vez.
  • GET /v1/auth/keysLista las claves de la organización (solo metadatos, sin secretos). Requiere keys:manage.
  • DELETE /v1/auth/keys/{id}Revoca una clave y todos sus descendientes (en cascada). Permitido para keys:manage o el padre de la clave.
DMARC

Informes agregados DMARC

Los proveedores de buzones (Gmail, Outlook, Yahoo, …) envían informes agregados DMARC (rua) diarios que resumen qué IPs de origen enviaron correo como tus dominios verificados y si SPF/DKIM/DMARC se alinearon. LoftBox los ingiere en informes estructurados para que puedas monitorizar la entregabilidad y detectar suplantación. Cada informe almacenado también registra el dominio del reportero autenticado.

  • GET /v1/dmarc/reportsLista los informes agregados DMARC de tu organización, los más recientes primero. Paginación por cursor mediante before_date_end + before_id (devueltos juntos como next_cursor). Requiere domain:read.
  • GET /v1/dmarc/reports/{id}Recupera un informe con sus registros por IP de origen (recuento de mensajes, disposición, alineación DKIM/SPF, header-from). Requiere domain:read.
curl -i "$BASE_URL/v1/dmarc/reports" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

curl -i "$BASE_URL/v1/dmarc/reports/REPORT_ID" \
  -H "Authorization: Bearer $LOFTBOX_API_KEY"

Los informes aparecen a medida que los proveedores los envían (normalmente una vez al día por reportero). Solo se devuelven los informes de tus propios dominios verificados; los informes de plataforma o de dominios no alojados nunca se exponen.

Eventos

Eventos de entrega

El estado de entrega se normaliza entre los callbacks de entrega gestionada y el estado de envío interno. Usa los IDs de evento y las referencias de entrega para soporte, no los datos privados del destinatario.

  • queued: aceptado por LoftBox para entrega.
  • sent: aceptado para entrega saliente.
  • delivered: se informó la entrega para el destinatario.
  • failed: la entrega falló de forma permanente o agotó los reintentos.
  • blocked: la política, el límite de tasa o el control de informes bloqueó el envío.
Controles

Límites de tasa y controles de informes

El envío saliente está limitado por la política de organización, agente, buzón, destinatario y dominio. Las organizaciones de beta personal tienen un tope de 100 envíos por día. Los mensajes de alto riesgo pueden retenerse para aprobación antes de intentar la entrega.

Gestiona 429 las respuestas aplicando backoff. No reintentes indefinidamente ni eludas las retenciones de aprobación desde otro buzón.

HTTP/1.1 429 Too Many Requests
Retry-After: 60
Controles de entrega

Entrega gestionada y configuración de seguridad

LoftBox opera la entrega saliente gestionada para las cuentas beta. La documentación pública debe describir los controles visibles para el cliente sin exponer nombres de proveedores internos, credenciales o detalles de enrutamiento.

  • Naturaleza del negocio: identidades de correo operativo gestionadas por API para agentes de IA con dominio verificado.
  • Tipos de correo: notificaciones transaccionales/del sistema, respuestas de agentes iniciadas por usuarios verificados, mensajes de onboarding/prueba y gestión de informes/contacto.
  • Controles: solo dominios verificados, límites de tasa explícitos, registros de entrega, gestión de supresión/quejas y contacto de informes monitorizado.
  • Páginas públicas: Privacidad, Términos, y Política antispam.

La propagación del DNS y las retenciones de verificación de entrega deben tratarse como estado de configuración, no como prueba de que el proxy de la API o la documentación de la página de inicio están rotos.