Email Agent CLI

Conceptos fundamentales

Email Agent conecta por IMAP y SMTP, persiste mensajes en Markdown y mantiene índices locales para consultas. No reemplaza el buzón remoto.

ROOT

Raíz de datos elegida por el usuario. Contiene el store, borradores, índices y estado local.

ACCOUNT_ID

Identificador público derivado o definido para una cuenta vinculada.

REL_PATH

Ruta relativa a un nodo Markdown bajo la raíz. Las rutas absolutas y el traversal se rechazan.

DRAFT_ID

SHA-256 determinista del contenido del borrador. Cambiar el contenido invalida el envío.

Instalación

Versión estable v0.2.3

Los instaladores verifican Python, pip y los SHA-256 de los wheels antes de instalar sin índice de paquetes.

powershell -File installers\install.ps1

sh installers/install.sh

Código actual del repositorio

git clone https://github.com/MauricioPerera/email-agent-kdd.git
cd email-agent-kdd
python -m pip install .
email-agent --help

El flujo bootstrap y send-gui descritos aquí está incluido en la release estable v0.2.3.

Inicio rápido asistido

bootstrap es reanudable, usa una raíz por usuario cuando no se proporciona --root y devuelve JSON para que un agente interprete el siguiente paso.

1. Diagnóstico de solo lectura

   email-agent bootstrap --check --json

2. Configuración mediante formulario local

   email-agent bootstrap --gui --lang es

   Un alta correcta termina en ready-to-sync; todavía no sincroniza.

3. Primera sincronización, después de autorización separada

   email-agent bootstrap --resume --sync
   email-agent bootstrap --resume --sync --sync-limit 50

Cuentas y diagnóstico

email-agent doctor [ROOT] [--fix] [--lang es|en|pt] [--format json|text] [--report FILE]
email-agent account setup-gui ROOT
email-agent account setup ROOT [--lang es|en|pt]
email-agent account add ROOT ACCOUNT_ID PROVIDER EMAIL CREDENTIAL_REF
email-agent account list ROOT
email-agent account remove ROOT ACCOUNT_ID CONFIRMAR DESVINCULAR
email-agent language set ROOT es|en|pt
email-agent language get ROOT

El formulario gráfico valida IMAP y SMTP sin enviar correo. Guarda la contraseña en Credential Manager, Keychain o Secret Service. El asistente de terminal solicita una referencia a variable de entorno, no la contraseña.

Sincronización

email-agent sync ROOT ACCOUNT_ID [HOST] [--limit N] [--unread]
email-agent watch ROOT ACCOUNT_ID [--every N] [--limit N] [--unread]

• sync es paginada, de solo lectura y conserva un cursor UID.
• --limit acepta de 1 a 100; el valor predeterminado de sync es 50.
• --unread limita la lectura a mensajes no leídos.
• watch repite mientras el proceso siga vivo; intervalo predeterminado 300 segundos y mínimo 30.

Búsqueda, lectura y contactos

email-agent query ROOT "INSTRUCTION" [--offset N] [--limit N] [--json]
email-agent search ROOT "QUERY" [--offset N] [--limit N] [--json]
email-agent read ROOT REL_PATH
email-agent contact list ROOT
email-agent contact show ROOT EMAIL
email-agent contact find ROOT TEXT [--offset N] [--limit N] [--json]

query admite términos libres y filtros para:, contact:, conversation:, topic: y account:. para: usa el destinatario real de entrega; contact: busca remitente o destinatarios de cabeceras.

Borradores y envío

email-agent draft ROOT ACCOUNT_ID TO SUBJECT BODY
email-agent draft show ROOT DRAFT_ID
email-agent send-gui ROOT ACCOUNT_ID DRAFT_ID
email-agent send ROOT ACCOUNT_ID DRAFT_ID CONFIRMAR ENVIO

send-gui es el camino recomendado con agentes: muestra el contenido exacto, requiere una casilla de revisión y ejecuta el envío en el mismo proceso. El camino terminal acepta la confirmación literal en la propia invocación.

Notificaciones

email-agent notification list ROOT
email-agent notification show ROOT NAME
email-agent notification add ROOT NAME QUERY
email-agent notification disable ROOT NAME CONFIRMAR REGLA
email-agent notification enable ROOT NAME CONFIRMAR REGLA
email-agent notification delete ROOT NAME CONFIRMAR REGLA

Las reglas se evalúan después de sincronizar y se deduplican por hash del mensaje. Reemplazar una regla existente también requiere CONFIRMAR REGLA.

Papelera local y remota

Store local

email-agent message delete ROOT REL_PATH
email-agent message trash ROOT
email-agent message restore ROOT TRASH_REL_PATH
email-agent message purge ROOT TRASH_REL_PATH CONFIRMAR BORRADO PERMANENTE

delete mueve el nodo a ROOT/.trash. Solo purge elimina definitivamente.

Buzón IMAP

email-agent message remote-delete ROOT ACCOUNT_ID UID TRASH_MAILBOX --uidvalidity N
email-agent message remote-restore ROOT ACCOUNT_ID UID TRASH_MAILBOX ORIGINAL_MAILBOX --uidvalidity N
email-agent message remote-purge ROOT ACCOUNT_ID UID MAILBOX CONFIRMAR BORRADO PERMANENTE --uidvalidity N

El movimiento remoto usa COPY + Deleted sin expunge. La purga selectiva solo continúa si el servidor anuncia UIDPLUS.

Adjuntos

email-agent attachment list ROOT REL_PATH
email-agent attachment download ROOT REL_PATH INDEX DEST CONFIRMAR EXTRACCION
email-agent attachment extract ROOT REL_PATH INDEX DEST CONFIRMAR EXTRACCION
email-agent attachment gc ROOT
email-agent attachment gc ROOT CONFIRMAR BORRADO ADJUNTOS
email-agent sync ROOT ACCOUNT_ID --attachments CONFIRMAR EXTRACCION

• La sincronización normal guarda metadatos, no bytes.
• Máximo 25 MB por adjunto y presupuesto predeterminado de 100 MB por sincronización con extracción.
• Los blobs son content-addressed, verificados por SHA-256 y escritos atómicamente.
• attachment gc ROOT es un dry-run; con confirmación elimina solo candidatos reconocidos y no referenciados.

Inicio automático

email-agent startup status ROOT ACCOUNT_ID
email-agent startup install ROOT ACCOUNT_ID --every 300 --limit 50 [--unread]
email-agent startup remove ROOT ACCOUNT_ID

Usa Task Scheduler en Windows, LaunchAgents en macOS y servicios systemd de usuario en Linux. Instalar el inicio automático cambia la configuración del sistema y requiere autorización directa.

Contrato de salidas y confirmaciones

Frases de autorización

Un usuario técnico puede incluir la frase correspondiente al ejecutar directamente el comando. Un agente nunca debe inventarla, guardarla ni reutilizarla por cuenta del usuario.