outlook-scan

outlook-scan — Acesso sob demanda à caixa de correio via Microsoft Graph

Uma CLI (outlook-scan, esperada no PATH) que consulta a caixa de correio em tempo real — somente leitura, a menos que o modo de escrita esteja ativado (apenas rascunhos). Nada é armazenado localmente, a menos que --save seja passado.

Regras básicas

• Stdout primeiro. Imprima os resultados na sessão; use --save DIR apenas quando o usuário explicitamente quiser manter arquivos (extração, arquivamento, anexos). Confirme ou escolha um diretório alvo óbvio.
• IDs de mensagem começam com AAMk, IDs de conversa com AAQk. Ambos são longos — sempre coloque-os entre aspas nos comandos. thread aceita qualquer um dos tipos.
• A ferramenta nunca pode enviar, mover, excluir ou marcar e-mails. Com o modo de escrita ativado, ela só pode criar rascunhos para o usuário revisar (veja abaixo).

Comandos

outlook-scan list [--folder NOME] [--unread] [--since 24h|7d|2w|AAAA-MM-DD] [--max N]
    # metadados, mais recentes primeiro: "N. [data] ● remetente — assunto 📎" + linha id
    # ● = não lido, 📎 = tem anexos. Pasta padrão Inbox, máximo 25.
    # Pastas: nomes de exibição ou apelidos (inbox, archive/archiv, sent,
    # drafts, trash, junk/spam — apelidos em inglês e alemão embutidos).

outlook-scan search [--max N] "consulta"
    # pesquisa full-text do lado do servidor em TODAS as pastas, ordenada por relevância

outlook-scan get [--save DIR [--attachments]] "ID-DA-MENSAGEM"
    # mensagem completa em markdown (cabeçalhos, nomes de anexos, corpo em texto simples)
    # --save DIR escreve o arquivo .md; --attachments baixa os arquivos adicionalmente

outlook-scan attachments [--save DIR] "ID-DA-MENSAGEM"
    # lista anexos (nome, tamanho, tipo); com --save: baixa-os

outlook-scan thread [--save DIR] "ID-DA-MENSAGEM-ou-ID-DA-CONVERSA"
    # conversa inteira em todas as pastas, em ordem cronológica, um documento

outlook-scan folders | status | login

Todos os comandos de leitura aceitam --json para saída estruturada.

Fluxos típicos

• "Verifique minha caixa de entrada" → outlook-scan list --unread (ou --since 24h), depois resuma; ofereça get para qualquer coisa que valha a pena ler por completo.
• "Encontre os e-mails sobre X" → outlook-scan search "X", apresente os resultados, get/thread sob solicitação.
• "Recupere a conversa inteira" → thread com o ID da mensagem de um list/search anterior.
• "Salve esse e-mail + anexos" → get --save DIR --attachments "ID".

Escrevendo rascunhos (opt-in, apenas se o modo de escrita estiver ativado)

Se esta instalação tiver o modo de escrita ativado (outlook-scan login --write), você pode criar RASCUNHOS — novas mensagens, respostas e encaminhamentos em conversas. Eles são salvos em Rascunhos e NUNCA são enviados — o usuário revisa e envia do Outlook.

# nova mensagem
outlook-scan draft --to "[email protected]" --cc "[email protected]" --assunto "..." --corpo "texto"
echo "texto mais longo" | outlook-scan draft --to "[email protected]" --assunto "..."

# resposta em conversa
outlook-scan reply [--all] --corpo "texto"            "ID-DA-MENSAGEM"
echo "texto de resposta mais longo" | outlook-scan reply       "ID-DA-MENSAGEM"
outlook-scan reply --all --body-file /caminho/resposta.txt "ID-DA-MENSAGEM"

# encaminhamento (anexos do original são carregados automaticamente)
outlook-scan forward --to "[email protected]" --corpo "FWI" "ID-DA-MENSAGEM"

--to/--cc/--bcc podem ser repetidos ou receber listas separadas por vírgula. Para corpos mais longos que uma linha ou duas, prefira pipe/--body-file em vez de --body para evitar problemas com aspas do shell.

O texto é simples por padrão; quebras de linha são preservadas. Adicione --html (todos os três comandos) quando o rascunho deve ter formatação — então o texto deve ser HTML, por exemplo, --html --body "<p>Olá <b>pessoal</b></p>". Não misture: texto simples passado com --html perde suas quebras de linha, e HTML passado sem --html aparece como tags visíveis.

Fluxos típicos: "crie um rascunho de resposta para X dizendo Y" → leia o e-mail com get/thread para contexto, componha, depois reply. "Escreva um e-mail para Z sobre Y" → draft. "Encaminhe isso para Z" → forward. Mostre ao usuário o texto que você pretende colocar no rascunho antes de criá-lo quando o texto for importante.

IDs de mensagem mudam quando uma mensagem é movida entre pastas. Se um comando de escrita retornar 404 ErrorItemNotFound, execute novamente list/search para obter o ID atual em vez de reutilizar um da sessão anterior.

Diga ao usuário que o rascunho está em Rascunhos para revisão — nunca implique que foi enviado. Se ocorrer o erro "modo de escrita está desativado", peça para ele executar outlook-scan login --write uma vez (consentimento único). Instalações somente leitura simplesmente não têm essa capacidade — isso é esperado.

E-mails S/MIME

E-mails com assinatura opaca são desembrulhados automaticamente em get/thread/attachments — corpo e anexos reais aparecem normalmente, marcados como "(desembrulhado de assinatura S/MIME opaca — não verificado)". Transmita essa ressalva de não verificação quando a autenticidade do e-mail for importante. E-mails criptografados mostram "🔒 criptografado (S/MIME)" — seu conteúdo NÃO é legível via API; diga ao usuário para abri-lo no Outlook.

Solução de problemas

• Erro nenhuma sessão — execute outlook-scan login (ou falha de atualização): execute outlook-scan login, repasse a URL impressa + código para o usuário, aguarde a conclusão. As sessões duram cerca de 90 dias silenciosamente.
• Erros de pasta não encontrada listam todos os nomes de pasta disponíveis.
• A pesquisa retorna no máximo 250 resultados (limite do Graph); refine a consulta.