Mailbox CLI

Gestión de correo electrónico centrada en la CLI para IMAP/SMTP de múltiples cuentas con caché de sincronización local.

Interfaz principal: la CLI mailbox (implementación en Node.js). Este repositorio distribuye binarios precompilados para la plataforma a través de npm (no se requiere Python para los usuarios finales).

Proveedores compatibles

• 163 Mail (mail.163.com / mail.126.com)

• QQ Mail (mail.qq.com)

• Gmail (mail.google.com)

• Outlook/Hotmail

• Servidores IMAP personalizados

Related MCP server: Email SMTP/IMAP MCP Server

Instalación

npm (recomendado)

npm install -g @leeguoo/mailbox-cli
mailbox --help

El paquete npm distribuye binarios precompilados por plataforma (no se requiere Python).

Como habilidad de IA (Claude Code / Cursor / etc.)

# Project scope — installs into ./.claude/skills/mailbox (or ./.cursor/skills/...):
npx skills add leeguooooo/Mailbox --skill mailbox

# User scope — installs into ~/.claude/skills/mailbox:
npx skills add leeguooooo/Mailbox --skill mailbox -g

La habilidad asume que la CLI está en el PATH (npm install -g @leeguoo/mailbox-cli). Para obtener la mayor aceleración, ejecute también mailbox daemon install una vez.

Servidor MCP (Claude Desktop / Code / Cursor)

mailbox mcp config --json   # prints a paste-ready mcpServers entry

Desde el código fuente (desarrollo)

pnpm install
pnpm test

# build a local platform binary into mailbox-cli/packages/<platform>/bin/mailbox
pnpm build:binary

Configurar cuentas

mkdir -p ~/.config/mailbox
cp examples/accounts.example.json ~/.config/mailbox/auth.json

Ubicaciones de configuración:

• Credenciales: ~/.config/mailbox/auth.json

• Otros ajustes: ~/.config/mailbox/config.toml

Comandos comunes

# CLI help
mailbox --help

# list accounts
mailbox account list --json

# list unread emails (cache by default)
mailbox email list --unread-only --limit 20 --json

# show one email
mailbox email show 123456 --account-id my_account_id --json

# mark read (use --dry-run to validate first)
mailbox email mark 123456 --read --account-id my_account_id --folder INBOX --dry-run --json
mailbox email mark 123456 --read --account-id my_account_id --folder INBOX --confirm --json

# delete
mailbox email delete 123456 --account-id my_account_id --folder INBOX --confirm --json

Caché + sincronización

• Base de datos de caché predeterminada: ~/.local/share/mailbox/email_sync.db

• El listado utiliza la caché de forma predeterminada siempre que sea posible. Añada --live para forzar IMAP.

mailbox sync status --json
mailbox sync force --json
mailbox sync init
mailbox sync daemon

Guía de uso de IA

Si está integrando esta CLI en un agente de IA, comience aquí:

• docs/AI_SKILL_MAILBOX_CLI.md

Integración con OpenClaw

Este repositorio incluye una habilidad de OpenClaw en skills/mailbox/SKILL.md.

OpenClaw carga las habilidades desde:

• <workspace>/skills

• ~/.openclaw/skills

Asistente de enlace rápido (enlace simbólico en ~/.openclaw/skills):

./scripts/link_openclaw_skill.sh

Forzar el reemplazo de un enlace existente:

./scripts/link_openclaw_skill.sh --force

Para usar este repositorio sin copiar archivos, añada el directorio de habilidades del repositorio a skills.load.extraDirs en ~/.openclaw/openclaw.json:

{
  "skills": {
    "load": {
      "extraDirs": [
        "/path/to/mcp-email-service/skills"
      ]
    }
  }
}

OpenClaw gestiona la entrega de canales y la programación; mailbox devuelve salidas JSON estructuradas y resúmenes de texto opcionales.

Verifique que OpenClaw haya detectado la habilidad:

openclaw skills list --eligible
openclaw skills check

Contrato

• docs/CLI_JSON_CONTRACT.md