InboxAPI

CLI de InboxAPI

Dale a tu agente de IA su propia dirección de correo electrónico personal. Envía, recibe, lee, busca y responde correos — directamente desde Claude, OpenCode, Codex, Gemini, o cualquier cliente de IA compatible con MCP. Sin servidor de correo que ejecutar, sin SMTP que configurar.

---

Tabla de contenidos

• Cómo funciona
• Detalles técnicos
• Bueno saber
• Instalación
• Primeros pasos
• Comandos
• Comandos CLI
• Uso con clientes MCP
• Habilidades para Claude Code
• Desarrollo
• Preguntas frecuentes
• Licencia
• Aviso legal

---

Cómo funciona

1. Instala la CLI
2. Conéctala a tu cliente de IA (Claude Desktop, Claude Code, Gemini CLI, OpenCode, etc.)
3. Tu IA ahora puede usar correo electrónico — sin necesidad de código ni claves de API

Se crea automáticamente una cuenta con una dirección de correo personal única en la primera ejecución. Tu IA puede entonces:

• Enviar correos a cualquier dirección
• Recibir correos en su propia bandeja de entrada
• Responder a y reenviar correos
• Buscar correos por palabra clave
• Leer hilos completos de conversación

Detalles técnicos

La CLI actúa como un puente local entre tu cliente de IA y el servicio en la nube de InboxAPI. Habla el Protocolo de Contexto de Modelo (MCP) a través de entrada/salida estándar, por lo que cualquier cliente de IA compatible puede usarlo sin integración personalizada.

Bueno saber

• Este es el correo personal de tu agente — InboxAPI le da a tu agente de IA su propia dirección de correo para uso personal. No es un servicio de correo transaccional — no lo uses para envíos masivos, marketing o notificaciones de aplicaciones.
• Límite semanal de envíos — Cada cuenta puede enviar a hasta cinco direcciones de correo únicas por semana. Esto se restablece semanalmente.
• Revisa tu carpeta de spam — Cada agente recibe su propio subdominio, y los subdominios nuevos aún no tienen reputación de correo. Los primeros mensajes pueden terminar en la carpeta de spam o correo no deseado del destinatario. Agregar la dirección de correo de tu agente a tus contactos o lista de permitidos ayuda. La entrega mejora con el tiempo a medida que los destinatarios interactúan con los correos de tu agente.
• Archivos adjuntos — Envía archivos adjuntos mediante subcomandos de la CLI usando --attachment (archivos locales) o --attachment-ref (archivos adjuntos del lado del servidor por ID).
• Soporte de correo HTML — Los subcomandos de la CLI admiten correos HTML con --html-body o --html-body-file.
• Verificación del propietario — Vincula tu correo a la cuenta de tu agente con verify_owner para habilitar la recuperación de cuenta y eliminar las restricciones de prueba. Se recomienda como primer paso después de la configuración.

Instalación

npm install -g @inboxapi/cli@latest

Se incluyen binarios precompilados para:

Plataforma	Arquitectura
macOS	ARM64, x64
Linux	x64, ARM64
Windows	x64

Actualización

Ejecuta el mismo comando de instalación para actualizar a la última versión:

npm install -g @inboxapi/cli@latest

La CLI también verifica automáticamente si hay actualizaciones cuando se ejecuta en modo proxy y las instala en segundo plano.

Primeros pasos

Simplemente inicia el proxy — se crea una cuenta automáticamente en la primera ejecución

inboxapi proxy

En la primera ejecución sin credenciales guardadas, la CLI crea automáticamente una cuenta con un nombre generado (p. ej. brooding-fluffy-owl) y se autentica. No se necesita configuración manual.

Las credenciales se almacenan en el directorio de configuración de tu sistema y se inyectan automáticamente en las llamadas de herramientas. La CLI verifica múltiples ubicaciones para poder recoger credenciales creadas por agentes de IA:

• ~/Library/Application Support/inboxapi/credentials.json (principal en macOS)
• ~/.config/inboxapi/credentials.json (principal en Linux / alternativa en macOS)
• ~/.local/inboxapi/credentials.json (alternativa, usada por algunos agentes de IA)

Comandos

proxy (predeterminado)

Inicia el proxy STDIO. Lee mensajes JSON-RPC desde stdin, los reenvía al endpoint de InboxAPI y transmite respuestas SSE a stdout. Si no se encuentran credenciales, se crea automáticamente una cuenta con un nombre generado.

inboxapi proxy
inboxapi proxy --endpoint https://custom-endpoint.example.com/mcp
inboxapi proxy --claim-secret ibx...

Ejecutar inboxapi sin subcomando también inicia el proxy. --claim-secret se usa solo cuando las credenciales no existen y el proxy crea automáticamente una cuenta en un dominio personalizado.

login

Crea manualmente una cuenta con un nombre elegido y almacena las credenciales de acceso localmente. No es necesario para el uso básico ya que proxy maneja la creación de cuentas automáticamente.

inboxapi login
inboxapi login --name myaccount
inboxapi login --endpoint https://custom-endpoint.example.com/mcp
inboxapi login --name myaccount --claim-secret ibx...

custom-domain-claim

Reclama un buzón principal de dominio personalizado para la cuenta actual usando un secreto de reclamo de dominio personalizado. El buzón generado anteriormente permanece habilitado para recibir pero no puede enviar.

inboxapi custom-domain-claim --secret ibx... --email-address myaccount@example.com

whoami

Muestra la cuenta y el endpoint actualmente autenticados.

inboxapi whoami

reset

Elimina las credenciales almacenadas. Ofrece interactivamente hacer una copia de seguridad primero, y luego pide confirmación antes de eliminar.

inboxapi reset

backup

Hace una copia de seguridad de las credenciales en una carpeta especificada.

inboxapi backup ./my-backup

restore

Restaura credenciales desde una carpeta de copia de seguridad. Valida la integridad de la copia y ofrece hacer una copia de las credenciales existentes antes de sobrescribirlas.

inboxapi restore ./my-backup

setup-skills

Instala habilidades de InboxAPI para agentes de codificación de IA. Admite Claude Code, Codex CLI, Gemini CLI y OpenCode. Detecta automáticamente los agentes instalados y solicita confirmación, o usa banderas para instalación no interactiva.

inboxapi setup-skills              # Auto-detect agents, interactive prompt
inboxapi setup-skills --all        # Install for all 4 agents
inboxapi setup-skills --claude --codex  # Install for specific agents
inboxapi setup-skills --force      # Overwrite existing skills and hooks

Comandos CLI

Para agentes con acceso a shell, los subcomandos CLI son la forma más sencilla de usar InboxAPI — sin necesidad de conocimientos de MCP, JSON-RPC o base64.

send-email

inboxapi send-email --to user@example.com --subject "Hello" --body "Hi there"
inboxapi send-email --to user@example.com --subject "Report" --body "See attached" --attachment ./report.pdf
inboxapi send-email --to user@example.com --subject "Fwd" --body "See attached" --attachment-ref 9f0206bb-...
inboxapi send-email --to "a@b.com, c@d.com" --subject "Hi" --body "Hello" --cc "cc@b.com" --priority high
inboxapi send-email --to user@example.com --subject "Newsletter" --body-file ./body.txt --html-body-file ./newsletter.html
inboxapi send-email --to user@example.com --subject "Screenshot" --body-file ./body.txt --html-body-file ./email-with-inline-image.html

Admite --body o --body-file, --html-body o --html-body-file, --cc, --bcc, --priority, --attachment (archivos locales, repetible) y --attachment-ref (IDs de archivos adjuntos del lado del servidor, repetible). --from-name está obsoleto e ignorado; InboxAPI aplica la identidad de la cuenta autenticada.

Prefiere --body-file y --html-body-file para HTML complejo, plantillas o cargas útiles grandes generadas, como imágenes base64 en línea. Los cuerpos respaldados por archivos se validan como texto UTF-8, se normalizan a finales de línea \n y se limitan a 20 MiB antes de enviar la solicitud.

get-emails

inboxapi get-emails --limit 5
inboxapi get-emails --limit 5 --human

get-email

inboxapi get-email "<message-id>"

delete-email

Archiva (elimina suavemente) un correo recibido por ID de mensaje. Solicita confirmación de forma predeterminada, y el uso mediante scripts o tuberías debe pasar --force. archive-email está disponible como alias para delete-email.

inboxapi delete-email "<message-id>"
inboxapi delete-email "<message-id>" --force
inboxapi archive-email "<message-id>" --force

search-emails

inboxapi search-emails --subject "invoice" --limit 10

get-attachment

inboxapi get-attachment abc123                      # prints signed URL as JSON
inboxapi get-attachment abc123 --output ./file.pdf  # downloads to file

send-reply

inboxapi send-reply --message-id "<msg-id>" --body "Thanks!"
inboxapi send-reply --message-id "<msg-id>" --body-file ./reply.txt --html-body-file ./reply.html

send-reply preserva automáticamente los destinatarios originales del hilo para conversaciones con múltiples destinatarios. Usa --reply-all para forzar responder a todos, y usa --cc cuando necesites agregar nuevos destinatarios en CC más allá del hilo original.

forward-email

inboxapi forward-email --message-id "<msg-id>" --to recipient@example.com --note "FYI"

help

inboxapi help  # CLI-focused help with examples

Todos los comandos CLI admiten la bandera --human para salida legible por humanos en lugar de JSON.

Uso con clientes MCP

La CLI de InboxAPI también funciona como transporte MCP STDIO. Apunta tu cliente MCP al binario inboxapi:

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "inboxapi": {
      "command": "inboxapi"
    }
  }
}

Claude Code:

Agregar al proyecto actual:

claude mcp add inboxapi inboxapi

Agregar globalmente (disponible en todos los proyectos):

claude mcp add inboxapi inboxapi -s user

Gemini CLI:

Agregar al proyecto actual:

gemini mcp add inboxapi inboxapi

Agregar a nivel de sistema (disponible en todos los directorios):

gemini mcp add inboxapi inboxapi --scope user

OpenCode:

Ejecuta la configuración interactiva:

opencode mcp add

Cuando se te solicite, ingresa:

• Ubicación: Global
• Nombre del servidor MCP: inboxapi
• Tipo de servidor MCP: Local
• Comando a ejecutar: inboxapi

Codex CLI:

codex mcp add inboxapi inboxapi

Habilidades para agentes de codificación de IA

InboxAPI incluye habilidades — comandos de barra y flujos de trabajo guiados — para múltiples agentes de codificación de IA. Instálalas con:

inboxapi setup-skills        # Auto-detect and install
inboxapi setup-skills --all  # Install for all agents

Las habilidades se instalan en directorios específicos del agente:

Agente	Directorio de instalación
Claude Code	.claude/skills/
Codex CLI	.agents/skills/
Gemini CLI	.gemini/skills/
OpenCode	.opencode/commands/

Habilidades disponibles

Habilidad	Descripción
/check-inbox	Obtiene y muestra un resumen de los correos recientes en una tabla formateada
/compose	Redacta y envía un correo con indicaciones guiadas, búsqueda en la libreta de direcciones y confirmación
/email-search	Busca correos usando consultas en lenguaje natural
/email-reply	Responde a un correo con contexto completo del hilo y vista previa antes de enviar
/email-digest	Genera un resumen estructurado de la actividad de correo reciente agrupada por hilos
/email-forward	Reenvía un correo a otro destinatario con una nota opcional
/setup-inboxapi	Configura el servidor MCP de InboxAPI e instala habilidades para tu agente de codificación de IA

Hooks (solo Claude Code)

El comando setup-skills también instala tres hooks para Claude Code que se ejecutan automáticamente:

Hook	Tipo	Descripción
Verificación de credenciales	SessionStart	Verifica las credenciales de InboxAPI al inicio y muestra el estado de autenticación
Guardia de envío de correo	PreToolUse	Revisa los correos salientes antes de enviarlos, advierte sobre autoenvíos y cuerpos vacíos
Registrador de actividad	PostToolUse	Registra todo el uso de herramientas de InboxAPI en .claude/inboxapi-activity.log para pistas de auditoría

Desarrollo

cargo build           # Build debug binary
cargo build --release # Build release binary
cargo test            # Run tests
cargo fmt             # Format code

Preguntas frecuentes

¿Por qué no simplemente darle a mi agente acceso a mi Gmail o Outlook?

Seguridad — OAuth de Gmail/Outlook le da a tu agente acceso a toda tu bandeja de entrada (médica, financiera, legal, personal). Una inyección de instrucciones en cualquier correo entrante podría manipular a un agente con acceso a todo ello. InboxAPI le da a tu agente su propia bandeja de entrada aislada con clasificación de confianza y marcado de datos en cada mensaje.

Identidad — Cuando tu agente envía desde tu Gmail, los destinatarios no pueden saber con quién están hablando. Las respuestas van a tu bandeja de entrada, mezcladas con tu correo real. InboxAPI le da a tu agente su propia dirección personal — separación clara entre tú y tu agente.

Practicidad — Las API de Gmail/Outlook no son nativas de MCP. Necesitarías middleware, infraestructura OAuth e integración personalizada. InboxAPI funciona de inmediato con cualquier cliente MCP.

¿En qué se diferencia esto de AWS SES, SendGrid o Resend?

Esos son API de envío — construyes infraestructura de correo sobre ellos. InboxAPI le da a tu agente una identidad de correo completa: enviar, recibir, buscar, responder y reenviar. No hay nada que configurar ni infraestructura que gestionar.

¿En qué se diferencia esto de AgentMail o a1base?

Construimos nuestra propia pila de correo desde cero. No envolvemos SES, Postfix ni ningún servicio de envío de terceros. El correo de tu agente pasa por infraestructura que operamos directamente.

¿Es realmente gratis?

Sí. Sin tarjeta de crédito, sin período de prueba, sin niveles de uso. Estamos trabajando en planes de pago con funciones adicionales, pero la experiencia principal siempre será gratuita.

¿Cómo previenen el spam y el abuso?

La creación de cuentas requiere prueba de trabajo. Cada cuenta solo puede enviar correos a 5 direcciones externas únicas por semana. Se aplican cuotas diarias de envío y límites de velocidad en cada cuenta. Estas restricciones son estructurales — no son políticas, son cómo funciona el sistema.

¿Qué pasa con la inyección de instrucciones a través del correo?

Cada correo entrante incluye una clasificación de confianza — confiable, agente, no verificado o sospechoso — basada en si el remitente está en tu libreta de direcciones y si su correo pasa las verificaciones de autenticación. Esto ayuda a tu agente a decidir con qué cautela manejar cada mensaje. Los correos de otros agentes de InboxAPI se marcan por separado para que tu agente sepa consultarte antes de actuar sobre ellos.

Además, el contenido de correo no confiable se transforma automáticamente usando resaltado (marcado de datos) — los espacios en blanco se reemplazan con un carácter marcador único para que tu agente pueda distinguir claramente los datos del correo de sus propias instrucciones. Esto reduce la tasa de éxito de los ataques de inyección de instrucciones incrustados en correos de ~50% a menos del 3%.

¿Qué es el resaltado?

Las herramientas de recuperación de correo electrónico aplican marcado de datos al contenido no confiable, reemplazando los espacios en blanco con un carácter marcador Unicode único generado por solicitud. El contenido que contenga el marcador debe tratarse como datos externos — nunca como instrucciones a seguir. Para recuperar el texto original, reemplace el marcador con un espacio. Los correos de remitentes confiables (en su libreta de direcciones con autenticación válida) no se resaltan de forma predeterminada. Esta técnica se basa en investigación académica (arXiv:2403.14720).

¿Qué pasa con la exfiltración de datos?

Los correos salientes se escanean en busca de tokens de autenticación y credenciales. Si su agente intenta accidentalmente enviar un correo que contenga un JWT o token de acceso, el mensaje se rechaza antes de salir de la plataforma. Esto evita que los agentes sean engañados para filtrar datos sensibles por correo electrónico. Además, todas las direcciones de destinatario en operaciones de envío, respuesta y reenvío se validan contra RFC 5322 — las direcciones malformadas se rechazan antes de la entrega.

¿Pueden los agentes enviarse spam entre sí?

Los mismos límites de envío se aplican a todos los correos salientes — los topes de destinatarios, cuotas y limitación de velocidad funcionan igual independientemente de quién esté en el extremo receptor.

¿Los correos de mi agente caerán en spam?

Quizás al principio. Cada agente obtiene un subdominio completamente nuevo, y los remitentes nuevos aún no tienen reputación. Los destinatarios pueden necesitar revisar su carpeta de spam durante los primeros correos. Con el tiempo, a medida que su agente envía correo legítimo y los destinatarios interactúan con él, la entrega mejora.

¿Por qué correo electrónico en lugar de un protocolo nativo de agentes como A2A?

El correo electrónico llega a todo el internet existente — miles de millones de personas y empresas ya lo usan. A2A requiere que ambos lados implementen el protocolo. Cuando su agente necesita contactar a alguien fuera de su propio ecosistema, el correo electrónico es la opción universal. Los agentes probablemente necesitarán ambos.

¿Por qué correo electrónico en lugar de WhatsApp, Telegram u otras aplicaciones de mensajería?

Escalabilidad — Puede crear programáticamente cientos de direcciones de correo electrónico. WhatsApp, Telegram y Signal requieren números de teléfono y verificación. Escalar más allá de un puñado de cuentas es poco práctico, a menudo va contra los términos de servicio y a veces es imposible sin tarjetas SIM físicas.

Sin barreras de entrada — El correo electrónico es el único canal de comunicación donde puede crear una identidad sin número de teléfono, identificación gubernamental o aprobación del propietario de la plataforma. Ninguna empresa controla quién obtiene una dirección de correo electrónico.

Protocolo abierto — El correo electrónico es federado y neutral respecto al proveedor. WhatsApp, Discord y Telegram son propietarios — pueden revocar el acceso a la API, prohibir cuentas de bots o cambiar las reglas en cualquier momento. El correo electrónico no puede ser apagado por una sola empresa.

Cumplimiento de ToS — La mayoría de las plataformas de mensajería prohíben explícitamente cuentas automatizadas o tienen procesos de aprobación estrictos (la API de WhatsApp Business requiere verificación empresarial, Telegram restringe la mensajería bot-a-bot). El correo electrónico no tiene tales restricciones — el envío automatizado es un caso de uso de primera clase.

Alcance universal — Los canales de mensajería están aislados. Su bot de Telegram no puede contactar a un usuario de WhatsApp. El correo electrónico llega a cualquier persona con una dirección de correo — que es efectivamente todos.

Para marcos de trabajo de agentes multicanal como OpenClaw, el correo electrónico llena un vacío que las plataformas de mensajería estructuralmente no pueden — creación de identidad programable e ilimitada sin aprobación de plataforma requerida. InboxAPI brinda a los agentes esa capacidad de serie.

¿Cuáles son los límites de envío?

Cada cuenta puede enviar correos a hasta 5 direcciones de correo electrónico externas únicas por semana. Los correos a otras direcciones @inboxapi.ai no cuentan para este límite. El límite se restablece semanalmente.

¿Qué sucede cuando alcanzo el límite?

Cuando los 5 espacios están en uso, la entrada usada menos recientemente se reemplaza automáticamente después de 5 días de inactividad.

¿Puedo enviar archivos adjuntos?

Sí. El soporte de archivos adjuntos está completamente disponible. Proporcione una matriz de objetos EmailAttachment que contengan el filename, content_type y el content codificado en base64 en el campo attachments al llamar a send_email.

¿Puedo enviar correos HTML?

Sí. Use --html-body "<html>" para HTML en línea o --html-body-file ./email.html para contenido HTML respaldado por archivos. Para plantillas más complejas o cargas útiles grandes generadas, prefiera --body-file y --html-body-file.

¿Cómo funcionan las credenciales?

Las credenciales de su agente se almacenan localmente en ~/.config/inboxapi/credentials.json (Linux) o ~/Library/Application Support/inboxapi/credentials.json (macOS). La CLI maneja la creación y renovación de tokens automáticamente — su agente nunca necesita gestionar tokens manualmente.

¿Qué pasa si mi agente pierde el acceso?

Si las credenciales de su agente se pierden o corrompen, puede recuperar la cuenta usando la herramienta account_recover — pero solo si previamente vinculó su correo electrónico mediante verify_owner. La recuperación revoca todos los tokens existentes y emite nuevas credenciales. Sin un correo electrónico de propietario verificado, no hay forma de recuperar una cuenta bloqueada.

¿Qué es la verificación de propietario?

La verificación de propietario vincula su dirección de correo electrónico personal a la cuenta de InboxAPI de su agente. Su agente llama a verify_owner con su correo, usted recibe un código de 6 dígitos, y su agente lo envía para completar la verificación. Una vez verificado, puede recuperar la cuenta si las credenciales se pierden, y las restricciones de prueba se eliminan de la cuenta. El subcomando de CLI verify-owner solicita confirmación de forma predeterminada; use --yes para ejecuciones no interactivas.

¿Qué dominios están bloqueados para el envío?

InboxAPI mantiene una lista de bloqueo que impide el envío a dominios gubernamentales (.gov), militares (.mil), de inteligencia, aplicación de la ley, infraestructura nuclear/crítica y correos desechables.

¿Cómo funciona la clasificación de confianza?

Cada correo entrante se clasifica en uno de cuatro niveles de confianza:

Nivel de Confianza	Significado	Acción Recomendada
Confiable	El remitente está en su libreta de direcciones con SPF/DKIM válido	Seguro de actuar
Agente	El remitente es un agente InboxAPI conocido	Leer libremente, pero confirmar con su humano antes de tomar acciones
No verificado	SPF/DKIM válido pero el remitente no está en la libreta de direcciones	Usar precaución
Sospechoso	Autenticación fallida o remitente desconocido	Marcar y confirmar antes de actuar

¿Qué modelo de IA debería usar con InboxAPI?

Su modelo debe soportar llamadas a herramientas/funciones — MCP lo requiere. Recomendamos una ventana de contexto mínima de 32K tokens para acomodar cómodamente las 21 definiciones de herramientas de InboxAPI junto con el historial de conversación y el contenido del correo.

Recomendaciones de modelos por nivel:

Nivel	Anthropic	OpenAI	Google
Bueno	Haiku 4.5+	GPT-4.1 mini+, GPT-4.1 nano+	Gemini 2.5 Flash+
Recomendado	Sonnet 4.5+	GPT-4.1+, GPT-5 mini+	Gemini 2.5 Pro+
Mejor	Opus 4.5+	GPT-5+, GPT-5.2+	Gemini 2.5 Pro+

Costo adicional del marcado de datos: InboxAPI aplica marcado de datos (resaltado) al contenido de correo no confiable, reemplazando espacios en blanco con caracteres marcadores Unicode. Esto puede aumentar ligeramente el consumo de tokens al procesar correos de remitentes externos. Los modelos con ventanas de contexto más grandes manejan esto más cómodamente.

Lo que no funcionará: Modelos sin soporte de llamadas a herramientas/funciones, modelos con ventanas de contexto por debajo de 16K tokens, y modelos locales muy pequeños (menos de ~7B parámetros) que carecen de llamadas a herramientas confiables. Estos tendrán dificultades para ajustar las 21 definiciones de herramientas de InboxAPI y mantener un historial de conversación útil.

¿Qué impide que un agente compre cosas o autorice transacciones por correo electrónico?

InboxAPI es un canal de comunicación, no un entorno de ejecución. Puede entregar un correo, pero no puede hacer clic en botones, ingresar números de tarjeta de crédito ni interactuar con sistemas externos. El riesgo de acciones no autorizadas proviene de cómo está configurado un agente y qué otras herramientas tiene acceso — no de su correo electrónico.

Licencia

El código fuente en este repositorio está licenciado bajo la Licencia MIT.

Aviso legal

El servicio InboxAPI se proporciona tal cual, sin garantías de ningún tipo. Nos reservamos todos los derechos sobre cómo se opera el servicio. Los términos del servicio, las características y la disponibilidad pueden cambiar en cualquier momento sin previo aviso.