codd-tech/imap-client

O que imap-client faz?

Leia caixas de correio via IMAP a partir do terminal usando myl, um cliente Python pequeno e de linha de comando. Mantido e distribuído por codd-tech. Projetado para ser integrado ao OpenClaw e a qualquer outro runtime compatível com AgentSkills (Claude Code, genérico).

myl é somente leitura e intencionalmente mínimo: ele lista, pesquisa e busca mensagens e anexos. Não envia e-mails, gerencia pastas ou modifica o estado, exceto opcionalmente marcando mensagens como lidas.

Como as credenciais chegam a esta habilidade

Esta é a seção mais importante. Você não digita senhas na linha de comando. As credenciais residem em variáveis de ambiente que o runtime injeta a cada execução do agente. A habilidade as lê e monta as flags corretas do myl por meio do wrapper em {baseDir}/scripts/imap.sh.

As variáveis que o wrapper espera:

Variável	Obrigatória	Finalidade
IMAP_USER	sim	Login (geralmente o endereço de e-mail completo)
IMAP_PASSWORD	sim	Senha específica do aplicativo (consulte references/authentication.md)
IMAP_PROVIDER	não	Um de auto (padrão), gmail, yandex, mailru, manual
IMAP_SERVER	apenas com manual	Host IMAP
IMAP_PORT	não	Padrão é 993
IMAP_STARTTLS	não	1 para adicionar --starttls (use apenas com a porta 143)

Defina-as uma vez, use-as em todas as sessões. Como depende do runtime — references/authentication.md cobre skills.entries.imap-client.env do OpenClaw, export genérico do shell e o arquivo de fallback ~/.config/imap-client/credentials. Não invente seu próprio esquema; use um desses três.

Se o wrapper detectar que IMAP_USER ou IMAP_PASSWORD está faltando, ele imprime as instruções de configuração e encerra sem contatar nenhum servidor. Esse é o sinal para parar e guiar o usuário na configuração das credenciais antes de tentar novamente.

Fluxo de trabalho de relance

1. Verifique se o myl está instalado. O OpenClaw protege esta habilidade com requires.bins: ["myl"], então ela não deve carregar sem ele. Para runtimes que não são OpenClaw, execute bash {baseDir}/scripts/check_myl.sh. Se estiver faltando, siga references/installation.md.
2. Confirme se as credenciais estão configuradas. Execute bash {baseDir}/scripts/imap.sh --count 1 >/dev/null uma vez. Sucesso significa que as variáveis de ambiente estão configuradas e a conexão funciona. Falha significa guiar o usuário por references/authentication.md.
3. Execute a operação solicitada por meio do wrapper. Listar, pesquisar, buscar por ID, obter HTML, salvar .eml bruto ou baixar um anexo.
4. Resuma o resultado. Não despeje corpos de e-mail brutos completos no chat, a menos que o usuário tenha solicitado.

Todo exemplo de myl nesta habilidade passa por {baseDir}/scripts/imap.sh, que expande variáveis de ambiente nas flags corretas do myl. Você não precisa lembrar --google vs --auto vs --server/--port; o wrapper escolhe com base em IMAP_PROVIDER.

Quando ler o quê

A tarefa envolve…	Leia
Detectar ou instalar o myl, proteção requires.bins do OpenClaw	references/installation.md
Configurar credenciais, escolher modo de conexão, senhas de aplicativo para Gmail / Yandex / Mail.ru / iCloud / Fastmail	references/authentication.md
Qualquer flag CLI específica, listar, pesquisar, buscar, anexos, nomes de pastas específicos do provedor	references/operations.md
Receitas de várias etapas (ex.: "encontre a fatura da Acme do mês passado e salve o PDF")	references/recipes.md
Erros como falhas SSL, "comando não encontrado", falha na descoberta automática, "AUTHENTICATIONFAILED", variáveis de ambiente não visíveis para o wrapper	references/troubleshooting.md

Princípios

1. As credenciais nunca aparecem nos comandos que você gera

Como as variáveis de ambiente são injetadas pelo runtime, o wrapper lida com elas internamente. Não gere comandos como myl -p hunter2 ou myl -p "$IMAP_PASSWORD" diretamente — ambos vazam. O primeiro cai no histórico do shell; o segundo expõe a senha em /proc/<pid>/cmdline enquanto o myl é executado. Use o wrapper, que mantém a senha dentro do próprio escopo do processo:

bash {baseDir}/scripts/imap.sh --count 5

O wrapper passa as credenciais para o myl via stdin quando suportado e, caso contrário, via flags que ele constrói internamente — mesma troca que o uso direto do myl, mas o literal da senha nunca aparece em nenhum comando que você escreveu, registrou ou mostrou ao usuário.

2. Padrão para conjuntos de resultados pequenos

Quando a intenção do usuário é exploratória ("algum e-mail novo?"), passe --count 5 ou --count 10. Busque janelas maiores apenas mediante solicitação explícita. Isso mantém a saída legível e evita despejar conteúdo confidencial que o usuário não pediu para ver.

3. Não marque como lido por acidente

--mark-seen altera o estado no servidor. Passe-o apenas quando o usuário solicitar explicitamente marcar mensagens como lidas. Listar ou ler sem esta flag é não destrutivo.

4. Renderize corpos longos em um arquivo, resuma no chat

Quando o usuário buscar uma mensagem longa ou e-mail em HTML, salve a saída bruta em um arquivo (ex.: /tmp/email-<id>.eml ou .html) e forneça ao usuário um resumo de 2 a 4 frases mais o caminho do arquivo. Não cole um corpo HTML de 500 linhas na conversa.

5. A sintaxe de pesquisa é IMAP do lado do servidor, não a IU da web do Gmail

--search "important" emite um comando IMAP SEARCH. Ele não entende os operadores from:, has:attachment ou label: do Gmail. Para filtragem complexa, busque uma janela razoável com --count e filtre a listagem localmente. Consulte references/operations.md para saber o que o IMAP SEARCH suporta.

6. Nunca ecoe, resuma ou persista a senha

Ao resumir o que você fez, refira-se à credencial como IMAP_PASSWORD ou "a senha da sua configuração do OpenClaw", nunca o valor literal. Se o usuário colar uma senha no chat por engano, trate-a como comprometida: diga a ele para trocá-la e atualizar a configuração. Não a escreva em nenhum artefato.

Árvore de decisão rápida

Usuário pediu algo relacionado a e-mail via CLI
  │
  ├─ O `myl` está instalado e no PATH?  ── Não  ──► references/installation.md
  │   │
  │   Sim
  │   ▼
  ├─ O teste de fumaça do wrapper passa?
  │     bash {baseDir}/scripts/imap.sh --count 1 >/dev/null
  │   │                       Não  ──► references/authentication.md
  │   Sim
  │   ▼
  ├─ O que o usuário deseja?
  │   ├─ Navegar / listar           ──► imap.sh --count N [--folder P]
  │   ├─ Pesquisar                  ──► imap.sh --search "TERMO" [--count N]
  │   ├─ Ler uma mensagem           ──► imap.sh "$IDEMAIL"
  │   ├─ Ler versão HTML            ──► imap.sh --html "$IDEMAIL"  → salvar em arquivo
  │   ├─ Salvar .eml bruto          ──► imap.sh --raw "$IDEMAIL" > arquivo.eml
  │   ├─ Obter anexo                ──► imap.sh "$IDEMAIL" "$NOMEANEXO" > arquivo
  │   └─ Qualquer coisa de várias etapas     ──► references/recipes.md
  │
  └─ Erros? ─────────────────────► references/troubleshooting.md

Estilo de saída

Após executar o wrapper, apresente os resultados neste formato:

• Status de uma linha sobre o que acabou de ser executado (ex.: "Listei as 10 mensagens mais recentes em INBOX").
• Uma tabela compacta ou lista com marcadores dos metadados da mensagem (data, de, assunto, ID).
• Quaisquer caminhos de arquivo onde a saída maior foi salva.
• Próximas ações sugeridas (ex.: "Quer que eu abra o #4582 ou salve seus anexos?").

Mantenha escaneável.