Agent Mailbox

Agent Mailbox proporciona a las pruebas automatizadas y a los agentes de IA direcciones de correo electrónico de corta duración para flujos de registro, verificación, enlaces mágicos y restablecimiento de contraseña. Se ejecuta en tu propia cuenta de Cloudflare y expone tanto una API JSON como un endpoint MCP sin estado.

Cada dirección tiene un token de buzón aleatorio separado. Los mensajes viven en un Durable Object respaldado por SQLite, los adjuntos viven en R2, y una alarma elimina el buzón cuando expira su tiempo de vida.

Inicio rápido

Necesitas Node.js 24 o superior y una cuenta de Cloudflare con al menos un dominio activo. Crea e implementa una copia nueva con:

npx create-agent-mailbox@latest

El paquete create-agent-mailbox estará disponible cuando se publique la primera versión pública. Hasta entonces, clona este repositorio y ejecuta:

pnpm install
pnpm run setup

La CLI de TypeScript utiliza el inicio de sesión del navegador de Wrangler, carga las zonas activas de tu cuenta y recomienda nombres de host dedicados mail.<domain> y mailbox.<domain>. Muestra un plan de implementación antes de realizar cualquier cambio. Una vez aprobado, configura Email Routing, subaddressing y Email Sending, ejecuta las comprobaciones del proyecto e implementa el Worker. Cloudflare aprovisiona el bucket R2, el Durable Object, los registros DNS y la regla de dirección entrante a partir de la configuración del Worker. La cuenta de la zona seleccionada se fija en la configuración generada del Worker, por lo que Wrangler no te pedirá que la elijas de nuevo.

El arrancador utiliza Corepack para instalar el lockfile exacto de pnpm del repositorio; no es necesario instalar pnpm globalmente.

Después de la implementación, el mismo flujo puede conectar Codex o Claude Code e instalar la habilidad Agent Mailbox incluida. El cliente recibe solo la ruta a un puente de credenciales local; la clave API permanece en el archivo de credenciales ignorado con modo 0600. Reinicia un cliente ya abierto después de conectarlo.

Cada zona seleccionada obtiene un Worker aislado con el nombre de la zona, como agent-mailbox-example-com. Puedes implementar Agent Mailbox para varios dominios en la misma cuenta de Cloudflare sin que una configuración reemplace el enrutamiento, almacenamiento, secretos o configuración de otro dominio. Mantén cada implementación de larga duración en su propio directorio de proyecto para que su configuración y credenciales generadas sigan disponibles; por ejemplo, usa npx create-agent-mailbox@latest mailbox-example-net para un segundo dominio.

Si Wrangler tiene varios perfiles de autenticación, la configuración pregunta cuál usar antes de cargar sus zonas. Un solo perfil se selecciona automáticamente. Para la configuración mediante scripts, pasa --profile <name> explícitamente.

El OAuth de Wrangler es suficiente; no necesitas crear un token de API de Cloudflare separado. Las comprobaciones de disponibilidad de DNS utilizan el resolutor DNS público de Cloudflare, y Wrangler maneja cualquier confirmación final de conflicto de dominio personalizado durante la implementación.

La CLI genera una clave API maestra y la envía a Wrangler a través de la entrada estándar, por lo que nunca aparece en la línea de comandos. Se escribe una copia local en el archivo ignorado .agent-mailbox.credentials.json con modo 0600; esta es la credencial que darás a los clientes API o MCP. Muévela a tu gestor de contraseñas si no quieres conservar la copia local.

Modos de configuración útiles:

# Validate local setup code and configuration. No login or Cloudflare changes.
pnpm mailbox deploy --check

# Log in, select a zone, and inspect DNS, but make no changes.
pnpm mailbox deploy --plan

# Scripted use after Wrangler is already authenticated.
pnpm mailbox deploy --zone example.com --yes

pnpm run setup sigue siendo un alias de compatibilidad para pnpm mailbox deploy.

Gestionar implementaciones

Agent Mailbox utiliza Cloudflare como fuente de verdad en lugar de mantener un segundo registro local:

# Find every Agent Mailbox Worker accessible to a Wrangler profile.
pnpm run list

# Check Worker bindings, custom domain, Email Routing, MX records, health,
# local credentials, and authenticated MCP connectivity.
pnpm run doctor

# Configure an installed MCP client and copy the portable Agent Skill.
pnpm run connect

# Safely remove one deployment after showing its exact Cloudflare resources.
pnpm run teardown

# Remove this checkout's MCP client connections and optionally its credentials.
pnpm run disconnect

# Empty and delete an R2 bucket retained by an earlier teardown.
pnpm run purge-data

list muestra qué implementación coincide con las credenciales en el checkout actual. doctor usa por defecto el Worker en wrangler.jsonc; pasa un nombre de Worker, dominio de correo o nombre de host MCP para inspeccionar otra instancia descubierta. Las comprobaciones MCP autenticadas se omiten para instancias cuya clave API no esté disponible localmente.

Para la configuración de cliente no interactiva, selecciona uno o más clientes explícitamente:

pnpm run connect --client codex --yes
pnpm run connect --client codex --client claude --yes

La habilidad incluida se instala en el directorio de habilidades de usuario del cliente seleccionado. Usa --no-skill si solo quieres la conexión MCP. Las conexiones de cliente existentes o los directorios de habilidades con contenido diferente no se modifican.

Eliminar una implementación

teardown selecciona una instancia descubierta y requiere su nombre completo de Worker como confirmación. Elimina solo la regla exacta de Email Routing entrante de ese Worker, el dominio personalizado, el Worker y el espacio de nombres del Durable Object. El DNS de Email Routing a nivel de zona compartido, el subaddressing, el Email Sending y otras implementaciones de Agent Mailbox permanecen sin cambios.

# Inspect the exact removal plan without changing Cloudflare.
pnpm run teardown -- agent-mailbox-example-com --dry-run

# Remove the Worker while retaining its R2 attachment bucket.
pnpm run teardown -- agent-mailbox-example-com

# Irreversibly empty and delete the attachment bucket as well.
pnpm run teardown -- agent-mailbox-example-com --purge-data

La operación está ordenada para que el Worker se elimine al final. Si un paso anterior falla, vuelve a ejecutar el mismo comando para continuar de forma segura. Para uso desatendido, proporciona la instancia, el perfil de Wrangler y --yes explícitamente.

Cuando teardown conserva adjuntos, escribe un recibo de limpieza ignorado con modo 0600 en el directorio del proyecto. Esto mantiene la cuenta y el bucket exactos descubribles después de que el Worker haya desaparecido. Elimínalo más tarde con:

pnpm run purge-data

Usa disconnect por separado para la limpieza local. Por defecto elimina las conexiones MCP seleccionadas y conserva tanto las credenciales como la habilidad compartida. El modo interactivo ofrece eliminar las credenciales coincidentes; el uso mediante scripts requiere --remove-credentials. Debido a que la habilidad puede servir a múltiples implementaciones, solo se elimina con la opción explícita --remove-skill.

Reimplementar, actualizar y rotar credenciales

Volver a ejecutar la configuración para el mismo dominio es una reimplementación segura. Si este proyecto tiene credenciales locales coincidentes, la configuración reinstala la misma clave API maestra en lugar de invalidar a los clientes conectados. Reemplazar la clave siempre requiere una elección explícita o --rotate-credentials.

Para actualizar una implementación desde una futura versión etiquetada, crea el nuevo código fuente sin implementar, copia la configuración generada y las credenciales ignoradas del proyecto anterior, revisa los cambios y luego ejecuta la configuración:

npx create-agent-mailbox@X.Y.Z agent-mailbox-next --no-deploy
cp agent-mailbox/wrangler.jsonc agent-mailbox/.agent-mailbox.credentials.json agent-mailbox-next/
cd agent-mailbox-next
corepack pnpm run setup
corepack pnpm run doctor

Mantén el directorio anterior hasta que doctor tenga éxito. Wrangler conserva versiones anteriores del Worker para la reversión. Si las credenciales locales no están disponibles, la configuración rechaza el reemplazo no interactivo a menos que se proporcione --rotate-credentials.

Modelo de seguridad

• Una clave API maestra protege cada solicitud API y MCP.

• Un token de buzón separado protege cada buzón creado.

• Los buzones expiran automáticamente después de como máximo el TTL máximo configurado.

• El correo entrante a direcciones desconocidas o expiradas se rechaza.

• Los contenidos de correo electrónico son datos no confiables. La extracción de enlaces y códigos es determinista.

• El envío saliente está limitado por buzón y está destinado solo a correos de prueba.

• Las respuestas API que contienen datos de buzón usan Cache-Control: no-store.

No expongas una implementación sin una clave API maestra fuerte. Este proyecto es una herramienta de prueba autoalojada, no un servicio público de correo desechable.

Requisitos

• Node.js 24 o superior. pnpm 10 solo se requiere cuando se desarrolla desde un clon.

• Una cuenta de Cloudflare con un dominio en Cloudflare.

• Acceso a Cloudflare Email Routing y Email Sending para ese dominio.

La CLI requiere subdominios dedicados en lugar de tomar un dominio raíz. Agent Mailbox crea direcciones como inbox+purpose-random@mail.example.com. Algunos servicios rechazan o normalizan los alias +; esos servicios pueden requerir una implementación dedicada de captura de todo en una futura versión.

Implementación manual

La CLI de configuración es la ruta recomendada. Estos son los pasos manuales equivalentes.

1. Configurar el Worker

Edita wrangler.jsonc y reemplaza cada valor example.com:

• name debe ser único para cada implementación de Agent Mailbox en la cuenta de Cloudflare.

• addresses[0] es la dirección base entrante, normalmente inbox@<EMAIL_DOMAIN>.

• routes[0].pattern es el nombre de host público de API y MCP.

• vars.EMAIL_DOMAIN es el dominio utilizado para las direcciones generadas.

• vars.MCP_HOSTNAME es el nombre de host permitido por el transporte MCP.

Si cambias los nombres de los enlaces, ejecuta pnpm exec wrangler types y confirma el worker-configuration.d.ts actualizado.

2. Aprovisionar funciones de correo a nivel de dominio

En el panel de Cloudflare, abre Compute → Email Service:

1. Incorpora el dominio receptor.

2. Habilita el subaddressing en su configuración de Email Routing.

3. Incorpora el mismo dominio en Email Sending.

La entrada addresses de Wrangler crea la regla de dirección entrante cuando se implementa el Worker, pero el DNS, el enrutamiento a nivel de zona, el subaddressing y la elegibilidad de envío ya deben estar configurados.

3. Verificar e implementar

pnpm check
pnpm deploy

Wrangler aprovisiona el bucket R2, el Durable Object, el nombre de host personalizado y la regla de dirección entrante desde wrangler.jsonc. Esto implementa la aplicación en tu cuenta de Cloudflare; no publica este repositorio Git.

4. Proteger la implementación

Crea un valor aleatorio largo en tu gestor de contraseñas y luego introdúcelo en el prompt interactivo de Wrangler:

pnpm exec wrangler secret put AGENT_API_KEY

Nunca pongas este valor en wrangler.jsonc, en un comando de shell o en el control de código fuente.

5. Verificar la implementación

Verifica el endpoint público de salud:

curl https://mailbox.example.com/health

Reemplaza el nombre de host con tu ruta configurada. Una respuesta exitosa es {"ok":true}.

Desarrollo local

pnpm install
cp .dev.vars.example .dev.vars
pnpm dev

Reemplaza el secreto de ejemplo en .dev.vars antes de iniciar el Worker. El estado local del Durable Object y R2 se almacena en el directorio ignorado .wrangler.

Ejecuta la suite de verificación completa con:

pnpm check

API JSON

Todas las rutas de buzón requieren la clave maestra:

Authorization: Bearer <AGENT_API_KEY>

Las operaciones específicas del buzón también requieren el token devuelto en la creación:

X-Mailbox-Token: <MAILBOX_TOKEN>

Crear un buzón

curl -X POST https://mailbox.example.com/api/mailboxes \
  -H "Authorization: Bearer $AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"purpose":"signup","ttlSeconds":3600}'

La respuesta contiene address, mailboxToken y expiresAt. Guarda el token del buzón; no se puede recuperar.

Esperar un correo de verificación

curl "https://mailbox.example.com/api/mailboxes/$ADDRESS/wait?subject=verify&timeoutSeconds=20" \
  -H "Authorization: Bearer $AGENT_API_KEY" \
  -H "X-Mailbox-Token: $MAILBOX_TOKEN"

Rutas:

• POST /api/mailboxes

• GET /api/mailboxes/:address/messages

• GET /api/mailboxes/:address/messages/:id

• GET /api/mailboxes/:address/messages/:id/links

• GET /api/mailboxes/:address/messages/:id/codes

• GET /api/mailboxes/:address/messages/:id/attachments/:index

• GET /api/mailboxes/:address/wait

• POST /api/mailboxes/:address/send

• DELETE /api/mailboxes/:address

• GET /health

Los índices de adjuntos provienen del array attachments devuelto con un mensaje completo y son de base cero.

MCP

El endpoint HTTP Streamable es https://<your-hostname>/mcp. Configura tu cliente MCP con esa URL y este encabezado:

Authorization: Bearer <AGENT_API_KEY>

Herramientas disponibles:

• create_mailbox

• wait_for_email

• list_emails

• get_email

• get_links

• get_codes

• send_email

• delete_mailbox

La configuración de cliente más fácil es:

pnpm run connect

Esto es compatible con Codex y Claude Code. Da a cada implementación un nombre de conexión MCP único, lo que permite a los clientes distinguir múltiples dominios de Agent Mailbox.

Puente stdio opcional

Los clientes MCP más antiguos pueden usar bin/agent-mailbox-mcp, que ejecuta mcp-remote desde las dependencias de este proyecto. Después de la configuración automatizada, lee el endpoint y la clave de .agent-mailbox.credentials.json:

bin/agent-mailbox-mcp

Puedes sobrescribir esos valores generados con variables de entorno:

export AGENT_MAILBOX_MCP_URL=https://mailbox.example.com/mcp
export AGENT_MAILBOX_API_KEY='<master-api-key>'
bin/agent-mailbox-mcp

Para clientes gráficos de Linux, almacena la clave en Secret Service en lugar de una variable de entorno y configura estos atributos de búsqueda no secretos:

export AGENT_MAILBOX_MCP_URL=https://mailbox.example.com/mcp
export AGENT_MAILBOX_KEYRING_SERVICE=agent-mailbox
export AGENT_MAILBOX_KEYRING_ACCOUNT=agent-mailbox
bin/agent-mailbox-mcp

Operaciones

• TTL de buzón predeterminado: un día.

• TTL máximo de buzón: siete días.

• Límite de envío predeterminado: 20 mensajes por buzón por día UTC.

• Los registros y trazas de Workers están habilitados en wrangler.jsonc; ajusta el muestreo según tu tráfico y presupuesto esperados.

• Eliminar o expirar un buzón también elimina sus adjuntos R2.

Trata la clave API maestra y cada token de buzón como credenciales. Los cuerpos de correo, encabezados, enlaces, códigos y adjuntos pueden contener datos personales o sensibles.

Soporte, contribuciones y seguridad

Abre un issue de GitHub para errores reproducibles, solicitudes de funciones y preguntas de uso comunes. Consulta CONTRIBUTING.md para obtener orientación sobre desarrollo y SECURITY.md para informar vulnerabilidades de forma privada. Nunca incluyas credenciales, contenidos de buzones o identificadores de implementación privados en un issue.

Licencia

Agent Mailbox está disponible bajo la Licencia MIT.