crux/outlook-scan

outlook-scan — acceso al buzón bajo demanda vía Microsoft Graph

Un CLI (outlook-scan, esperado en PATH) que consulta el buzón en tiempo real - solo lectura a menos que el modo de escritura esté activado (solo borradores). No se almacena nada localmente a menos que se pase --save.

Reglas básicas

• Primero stdout. Imprime los resultados en la sesión; usa --save DIR solo cuando el usuario quiera explícitamente archivos guardados (extracción, archivado, adjuntos). Confirma o elige un directorio destino obvio.
• Los IDs de mensajes comienzan con AAMk, los IDs de conversación con AAQk. Ambos son largos; cítalos siempre en los comandos. thread acepta cualquiera de los dos.
• La herramienta nunca puede enviar, mover, eliminar ni marcar correos. Con el modo de escritura activado solo puede crear borradores para que el usuario los revise (ver más abajo).

Comandos

outlook-scan list [--folder NOMBRE] [--unread] [--since 24h|7d|2w|AAAA-MM-DD] [--max N]
    # metadatos, más reciente primero: "N. [fecha] ● remitente — asunto 📎" + línea de ID
    # ● = no leído, 📎 = tiene adjuntos. Carpeta predeterminada Bandeja de entrada, máx. 25.
    # Carpetas: nombres para mostrar o alias (inbox, archive/archiv, sent,
    # drafts, trash, junk/spam — alias en inglés y alemán incluidos).

outlook-scan search [--max N] "consulta"
    # búsqueda de texto completo del lado del servidor en TODAS las carpetas, ordenada por relevancia

outlook-scan get [--save DIR [--attachments]] "ID-DEL-MENSAJE"
    # mensaje completo en markdown (encabezados, nombres de adjuntos, cuerpo en texto plano)
    # --save DIR escribe archivo .md; --attachments descarga además los archivos

outlook-scan attachments [--save DIR] "ID-DEL-MENSAJE"
    # lista de adjuntos (nombre, tamaño, tipo); con --save: descargarlos

outlook-scan thread [--save DIR] "ID-DEL-MENSAJE-o-ID-DE-CONVERSACIÓN"
    # conversación completa en todas las carpetas, en orden cronológico, un solo documento

outlook-scan folders | status | login

Todos los comandos de lectura aceptan --json para salida estructurada.

Flujos típicos

• "Revisa mi bandeja de entrada" → outlook-scan list --unread (o --since 24h), luego resume; ofrece get para cualquier cosa que valga la pena leer completa.
• "Encuentra los correos sobre X" → outlook-scan search "X", presenta resultados, get/thread a solicitud.
• "Trae toda la conversación" → thread con el ID del mensaje de una lista/búsqueda anterior.
• "Guarda ese correo + adjuntos" → get --save DIR --attachments "ID".

Redactar borradores (opt-in, solo si el modo de escritura está activado)

Si esta instalación tiene el modo de escritura habilitado (outlook-scan login --write), puedes crear BORRADORES: mensajes nuevos, respuestas en hilo y reenvíos. Se guardan en Borradores y NUNCA se envían: el usuario los revisa y envía desde Outlook.

# mensaje nuevo
outlook-scan draft --to "[email protected]" --cc "[email protected]" --subject "..." --body "texto"
echo "texto más largo" | outlook-scan draft --to "[email protected]" --subject "..."

# respuesta en hilo
outlook-scan reply [--all] --body "texto"                            "ID-DEL-MENSAJE"
echo "texto de respuesta más largo" | outlook-scan reply              "ID-DEL-MENSAJE"
outlook-scan reply --all --body-file /ruta/respuesta.txt              "ID-DEL-MENSAJE"

# reenviar (los adjuntos del original se transfieren automáticamente)
outlook-scan forward --to "[email protected]" --body "FYI" "ID-DEL-MENSAJE"

--to/--cc/--bcc se repiten o aceptan listas separadas por comas. Para cuerpos más largos que una o dos líneas, prefiere usar tubería/--body-file en lugar de --body para evitar problemas de comillas del shell.

El texto es plano por defecto; los saltos de línea se conservan. Agrega --html (los tres comandos) cuando el borrador deba llevar formato; entonces el texto debe ser HTML, p. ej., --html --body "<p>Hola <b>qué tal</b></p>". No mezcles: el texto plano pasado con --html pierde los saltos de línea, y el HTML pasado sin --html se muestra como etiquetas visibles.

Flujos típicos: "redacta una respuesta a X diciendo Y" → lee el correo con get/thread para contexto, redacta, luego reply. "Escribe un correo a Z sobre Y" → draft. "Reenvía eso a Z" → forward. Muestra al usuario el texto que piensas poner en el borrador antes de crearlo cuando la redacción sea importante.

Los IDs de mensajes cambian cuando un mensaje se mueve entre carpetas. Si un comando de escritura devuelve 404 ErrorItemNotFound, vuelve a ejecutar list/search para obtener el ID actual en lugar de reutilizar uno de antes en la sesión.

Informa al usuario que el borrador está en Borradores para revisión; nunca insinúes que fue enviado. Si aparece el error "el modo de escritura está desactivado", dile que ejecute outlook-scan login --write una vez (un consentimiento único). Las instalaciones de solo lectura simplemente no tienen esta capacidad, lo cual es normal.

Correos S/MIME

Los correos con firma opaca se desempaquetan automáticamente en get/thread/attachments

• el cuerpo y los adjuntos reales aparecen con normalidad, etiquetados como "(desempaquetado de la firma S/MIME opaca - no verificado)". Comunica esa advertencia de falta de verificación cuando la autenticidad del correo sea importante. Los correos cifrados muestran "🔒 cifrado (S/MIME)" - su contenido NO es legible a través de la API; indícale al usuario que lo abra en Outlook en su lugar.

Solución de problemas

• Error no hay sesión — ejecuta outlook-scan login (o fallo de actualización): ejecuta outlook-scan login, transmite la URL impresa + el código al usuario, espera a que termine. Las sesiones duran ~90 días de forma silenciosa.
• Los errores de carpeta no encontrada listan todos los nombres de carpeta disponibles.
• La búsqueda devuelve un máximo de 250 resultados (límite de Graph); refina la consulta.