cfmail · Dale a tu agente un buzón que pueda usar por su cuenta

Inglés | 简体中文

Qué es esto

El objetivo es simple: permitir que un agente reciba y envíe correo por su cuenta, sin que un humano tenga que reenviar, aprobar o hacer clic en «enviar» en el medio. Se ejecuta en Cloudflare y no tiene interfaz web — no es una bandeja de entrada para que tú la explores; es un buzón para que una IA/un programa lo use como propio.

El correo enviado a anything@your-domain se captura y se almacena automáticamente. El agente lo busca, lee el texto completo, responde y reenvía archivos adjuntos por su cuenta: no tienes que reenviarle el correo, y él no tiene que esperar a que hagas clic en enviar.

Someone emails you ──▶ Cloudflare receives it ──▶ parsed automatically, stored in a database and object storage
                                                              │
Agent ──asks a question / sends mail──▶ cfmail CLI (or MCP directly) ──▶ this service's API ──┘

El coste inicial es casi cero — basta con los planes gratuitos de Cloudflare y Resend, y ninguno requiere tarjeta de crédito:

Para un proyecto pequeño usado por una persona o un puñado de agentes, es difícil alcanzar estos límites; puedes ampliarlos más adelante si el volumen crece de verdad.

Es adecuado para estas situaciones:

• Dale a un agente un buzón que sea realmente suyo, para que pueda completar de forma independiente todo el ciclo «recibir → entender → responder/reenviar» sin ningún paso manual en el medio.

• Recibe códigos de verificación, notificaciones, recibos, facturas en tu propio dominio y deja que la IA los encuentre y los organice por ti.

• Sincroniza el correo —cuerpo y archivos adjuntos— al disco local según un horario, y recibe un mensaje de chat con un archivo local en el que se puede hacer clic en el momento en que llega correo nuevo.

Los detalles técnicos (esquema de base de datos, diseño de búsqueda, desglose de componentes, el diseño de doble backend de envío) están en ARCHITECTURE.md.

Este documento tiene dos partes: Configuración — desplegar el servicio en tu propia cuenta de Cloudflare; y Uso — una vez desplegado, cómo permitir que un agente lo use para enviar y recibir correo.

Related MCP server: gmail-mcp

Configuración: despliegue en Cloudflare (~10 minutos)

Todo ocurre en tu propia cuenta de Cloudflare: el correo solo vive bajo tu cuenta, nadie más puede acceder a él.

Qué necesitas

1. Una cuenta de Cloudflare (el plan gratuito es suficiente).

2. Un dominio ya añadido a esa cuenta (se usa tanto para recibir correo como para acceder al servicio).

3. Node.js 18 o superior instalado localmente.

Paso 0: obtén el código, inicia sesión y crea tu configuración local

git clone <this-repo> && cd cfmail
npm install
npx wrangler login                       # log into your Cloudflare account in the browser
cp wrangler.jsonc wrangler.local.jsonc   # your private config, never pushed to the repo

Todo lo que está vinculado a tu cuenta —tu dominio, ID de base de datos— va en wrangler.local.jsonc. Ya está ignorado por git; todos los comandos siguientes lo detectan automáticamente.

Paso 1: crea la base de datos (almacena metadatos y cuerpos del correo)

npx wrangler d1 create email_db

El comando imprime un database_id: cópialo en wrangler.local.jsonc, en d1_databases[0].database_id.

Paso 2: crea el almacenamiento de objetos (almacena el correo sin procesar y los archivos adjuntos)

npx wrangler r2 bucket create email-store

Paso 3: configura tu dominio

Abre wrangler.local.jsonc y cambia routes[0].pattern al subdominio que quieras, p. ej. mail.yourdomain.com (debe ser un dominio de tu cuenta de Cloudflare). Esta dirección es a la que se conectará el agente.

Paso 4: crea las tablas, establece una contraseña de acceso y despliega

npm run db:remote                        # create the tables
npx wrangler secret put MCP_TOKEN        # set an access password (see below)
npm run deploy                           # deploy

Contraseña de acceso: después de ejecutar ese comando, pega una cadena aleatoria suficientemente larga como contraseña: openssl rand -hex 32 funciona. El agente necesita esta contraseña para conectarse; nunca la filtres. Para rotarla, solo vuelve a ejecutar el comando: la contraseña antigua deja de funcionar de inmediato.

Paso 5: enruta el correo entrante a este servicio

Envía todo el correo dirigido a tu dominio a este servicio (una configuración que se hace una sola vez):

# replace <ZONE_ID> with your domain's Zone ID, and <API_TOKEN> with a Cloudflare API token that has "Email Routing edit" permission
curl -X PUT "https://api.cloudflare.com/client/v4/zones/<ZONE_ID>/email/routing/rules/catch_all" \
  -H "Authorization: Bearer <API_TOKEN>" -H "Content-Type: application/json" \
  --data '{"enabled":true,"name":"catch-all to worker","matchers":[{"type":"all"}],"actions":[{"type":"worker","value":["cloudflare-email"]}]}'

¿Prefieres hacerlo desde el panel? Panel de Cloudflare → tu dominio → Email Routing → Catch-all → acción «Send to a Worker» → elige cloudflare-email.

Si este dominio nunca ha tenido Email Routing activado, actívalo primero en el panel (añade automáticamente los registros DNS que la entrega de correo necesita).

¡Hecho! El correo para anything@your-domain ya se captura, y el servicio está activo en https://your-subdomain. Para comprobarlo: envía un correo de prueba a test@your-domain; en unos segundos, npx wrangler tail cloudflare-email debería mostrarlo mientras se procesa; el agente podrá encontrarlo una vez que hayas configurado «Uso» más abajo.

Opcional: habilita el envío

Si omites este paso, el servicio solo podrá recibir correo, no enviarlo. Se admiten dos backends, y Resend es el predeterminado:

Opción uno, Resend (recomendada):

1. Regístrate en Resend y añade tu dominio: usa el dominio raíz (yourdomain.com) directamente, sin necesidad de un subdominio.

2. Añade los tres registros DNS que te da, en el DNS de Cloudflare:

   Tipo	Nombre	Valor	Proxy
   MX	send	la dirección que te da Resend, prioridad 10	—
   TXT	send	v=spf1 include:amazonses.com ~all	—
   TXT	resend._domainkey	la clave pública DKIM que te da Resend	Solo DNS (nube gris)

   Este registro MX vive en send.yourdomain.com, así que no entra en conflicto con Email Routing en el dominio raíz. El registro DKIM debe tener el proxy desactivado; dejarlo activado hace que la verificación falle.

3. Establece la clave como secreto: npx wrangler secret put RESEND_API_KEY -c wrangler.local.jsonc

El plan gratuito es de 3,000 correos/mes, 100/día: suficiente para empezar; paga a medida que crezcas, o cambia a la opción de abajo.

Opción dos, envío integrado de Cloudflare: confirma que wrangler.local.jsonc tiene "send_email": [{ "name": "EMAIL" }] (ya está en la plantilla) y luego realiza una incorporación única de Email Sending para tu dominio en el panel de Email de Cloudflare. Si solo vas a enviar a direcciones que ya has verificado en Email Routing → Destination addresses, puedes omitir por completo la incorporación y enviar gratis de inmediato.

Si no hay ninguna configurada, el envío devuelve un mensaje «no send backend available» que explica qué configurar; la recepción y las consultas no se ven afectadas. Para más detalles sobre el envío —límites de tamaño de archivos adjuntos, restricciones del remitente, cómo depurar un error—, consulta ARCHITECTURE.md y cli/README.md; cuando un envío falla, el agente lee el código de error y te dice qué ha ido mal, así que no necesitas memorizar estos límites de antemano.

Mantenimiento continuo tras el despliegue

npx wrangler tail cloudflare-email        # tail incoming mail and errors live
npx wrangler secret put MCP_TOKEN         # rotate the access password
npx wrangler d1 execute email_db --remote --command "SELECT id,subject,from_addr,date FROM emails ORDER BY date DESC LIMIT 10"

wrangler.local.jsonc solo existe en tu máquina: no lo borres por accidente. Si lo haces, repite el «Paso 0» y vuelve a poner tu ID de base de datos y tu dominio.

Uso: deja que un agente envíe y reciba correo

Una vez desplegado, hay tres formas de conectarlo a un agente. Las skills son la vía recomendada — es la menos complicada y la más cercana al objetivo de «que el agente gestione el correo por su cuenta».

Opción preferida: usar las skills (recomendada)

El directorio skills/ contiene dos skills que enseñan a un agente a trabajar con la herramienta de línea de comandos cfmail:

skills/
  email-inbox/   for a regular user: read and send mail with a bound Key
  email-admin/   for an admin: open mailboxes, issue/revoke Keys, configure new-mail alerts

Las dos funcionan juntas: el administrador usa email-admin para emitir una clave para una dirección de buzón, y el usuario coloca esa clave en email-inbox para enviar y recibir correo.

Paso 0: instala cfmail (requiere Node 20+):

npm install -g cfmail

Paso 1: copia las skills al directorio de skills del agente. Para Claude Code, es .claude/skills/:

cp -r skills/email-inbox  your-project/.claude/skills/
cp -r skills/email-admin  your-project/.claude/skills/

También puedes crear un enlace simbólico de todo el directorio skills/: ln -s /path/to/cfmail/skills your-project/.claude/skills.

Paso 2 (administrador): abre un buzón:

cfmail admin setup --base https://your-subdomain --key <admin-MCP_TOKEN>   # one-time
cfmail admin create-key alice@your-domain                                 # prints a plaintext Key, shown only once

Otros comandos de administrador: list-keys (ver lo que se ha emitido), delete-key <address> (revocar), webhook --set whk_xxx (enviar correo nuevo al chat, opcional — consulta cli/README.md).

Paso 3 (usuario): configura esa clave:

cfmail setup --base https://your-subdomain --email alice@your-domain --key <the-key-from-step-2>

Una vez configurada, solo habla con el agente:

• «Comprueba si hay correo nuevo» / «Encuentra el correo con el código de verificación»

• «Responde al correo de la factura y confirma que lo hemos recibido»

• «Reenvía ese archivo adjunto a contabilidad»

Elige el comando adecuado por su cuenta: lee el texto completo, obtiene los archivos adjuntos y responde según sea necesario. El correo siempre se envía desde la dirección vinculada a la clave; eso se aplica en el servidor y no se puede cambiar.

Si además quieres sincronizar el correo al disco local, con un aviso en el chat que incluya un enlace de archivo en el que se pueda hacer clic cuando llegue correo nuevo — eso es un complemento aparte y opcional, fuera del flujo de las skills:

cfmail sync --dir ~/cfmail --notify whk_your-key

Ponlo en una programación con launchd/cron. El diseño de directorios, las reglas de deduplicación y en qué se diferencia de admin webhook están todos en cli/README.md.

Nota de seguridad: email-admin contiene la clave de administrador con mayores privilegios: consérvala solo en la máquina del administrador; nunca se la entregues a un usuario normal.

Alternativa: usa la línea de comandos de cfmail directamente

Sin las skills, un agente (o tú) puede simplemente ejecutar comandos:

cfmail unread                                              # fetch the latest unread mail
cfmail search "invoice"                                    # full-text search, Chinese included
cfmail read <email-id>                                     # read the full text and attachment list
cfmail send --to a@x.com --subject "subject" --text "body"  # send one
cfmail reply <email-id> --text "reply text"                 # reply within the original thread
cfmail config                                              # see which mailbox this config points at

Gestión de varios buzones en una sola máquina, ejecución de varios agentes a la vez, el diseño del archivo local y todas las opciones: la referencia completa está en cli/README.md (todos los comandos también responden a --help).

Alternativa: omite el CLI y conecta el servicio como MCP directamente

Si prefieres no instalar el CLI, puedes apuntar un cliente de IA compatible con MCP directamente al servicio:

claude mcp add --transport http email https://your-subdomain/mcp \
  --header "Authorization: Bearer your-password"

Otros clientes MCP usan un archivo de configuración:

{
  "mcpServers": {
    "email": {
      "url": "https://your-subdomain/mcp",
      "headers": { "Authorization": "Bearer your-password" }
    }
  }
}

Una vez conectado, solo pregunta en lenguaje natural: «busca el correo que contenga 'factura'», «abre el primero y descarga el archivo adjunto»; internamente, esto usa herramientas como search_emails / list_emails / get_email / get_attachment / send_email, elegidas automáticamente por la IA; no necesitas recordar sus nombres. Esta vía no te ofrece archivo local ni gestión de varios buzones: eso es exclusivo de cfmail.

Preguntas frecuentes

• La URL del servicio no carga / se restablece la conexión: no uses el *.workers.dev predeterminado (bloqueado en algunas regiones): usa tu propio dominio (que es lo que este proyecto hace por defecto).

• Un correo de prueba que enviaste rebotó (550 SPF): es un problema de validación del lado del remitente; enviar desde un buzón normal (Gmail, QQ, Outlook, etc.) no se ve afectado.

• Un correo que acabas de enviar aún no aparece: hay unos segundos de retraso entre la recepción y la indexación: espera y vuelve a comprobarlo, o usa npx wrangler tail cloudflare-email para ver si ha llegado.

• Recibes un 401: comprueba que Authorization: Bearer your-password está configurado correctamente.

Para colaboradores: desarrollo local

cp .dev.vars.example .dev.vars                 # fill in a local access password
npm run db:local                               # create local database tables
npm run dev                                     # start locally on :8787
MCP_TOKEN=your-local-password node scripts/mcp-smoke.mjs    # smoke-test the local API
npm test                                        # unit tests
npm run typecheck                               # type checking

Prueba de humo contra producción: BASE="https://your-subdomain" TOKEN="your-password" node scripts/remote-check.mjs

Licencia

MIT — libre de usar, modificar y distribuir.