Pular para o conteúdo principal

Documentação oficial desta página · v0.20.6

Configuração de E-mail

O Hermes consegue receber e responder e-mails usando os protocolos padrão IMAP e SMTP. Mande um e-mail para o endereço do agente e ele responde na mesma conversa — sem cliente especial nem API de bot. Funciona com Gmail, Outlook, Yahoo, Fastmail ou qualquer provedor que suporte IMAP/SMTP.

Só o adaptador de gateway: sem dependências externas

Esta página cobre o adaptador de gateway de E-mail, que usa os módulos embutidos do Python imaplib, smtplib e email. Nenhum pacote adicional nem serviço externo é necessário para este caminho de gateway.

Isso é diferente da skill de e-mail Himalaya que vem empacotada, que deixa o agente gerenciar e-mail por comandos de terminal e exige a CLI externa himalaya mais um arquivo de configuração do Himalaya.

Caso de usoO que configurarDependência externa
Deixar que pessoas mandem e-mail ao agente Hermes e recebam respostasAdaptador de gateway de e-mail desta páginaNenhuma além de uma conta de e-mail IMAP/SMTP
Deixar o agente inspecionar, redigir, mover e gerenciar mensagens da caixa postal com ferramentas de terminalSkill de e-mail HimalayaCLI himalaya e ~/.config/himalaya/config.toml

Pré-requisitos​

  • Uma conta de e-mail dedicada ao seu agente Hermes (não use o seu e-mail pessoal)
  • IMAP habilitado na conta de e-mail
  • Uma senha de aplicativo, se você usa Gmail ou outro provedor com autenticação em duas etapas

Configuração do Gmail​

  1. Ative a autenticação em duas etapas na sua Conta do Google
  2. Vá em Senhas de app
  3. Crie uma senha de app nova (selecione "E-mail" ou "Outro")
  4. Copie a senha de 16 caracteres — você vai usá-la no lugar da sua senha comum

Outlook / Microsoft 365​

  1. Vá em Configurações de segurança
  2. Ative a autenticação em duas etapas, se ainda não estiver ativa
  3. Crie uma senha de app em "Opções de segurança adicionais"
  4. Host IMAP: outlook.office365.com, host SMTP: smtp.office365.com

Outros provedores​

A maioria dos provedores de e-mail suporta IMAP/SMTP. Confira na documentação do seu provedor:

  • Host e porta de IMAP (em geral porta 993 com SSL)
  • Host e porta de SMTP (em geral porta 587 com STARTTLS)
  • Se senhas de app são obrigatórias

Passo 1: Configure o Hermes​

O jeito mais fácil:

hermes gateway setup

Escolha Email no menu de plataformas. O assistente pergunta o seu endereço de e-mail, a senha, os hosts de IMAP/SMTP e os remetentes permitidos.

Configuração manual​

Acrescente ao ~/.hermes/.env:

# Obrigatório
EMAIL_ADDRESS=hermes@gmail.com
EMAIL_PASSWORD=abcd efgh ijkl mnop    # Senha de app (não a sua senha comum)
EMAIL_IMAP_HOST=imap.gmail.com
EMAIL_SMTP_HOST=smtp.gmail.com

# Segurança (recomendado)
EMAIL_ALLOWED_USERS=voce@email.com,colega@trabalho.com

# Opcional
EMAIL_IMAP_PORT=993                    # Padrão: 993 (IMAP SSL)
EMAIL_SMTP_PORT=587                    # Padrão: 587 (SMTP STARTTLS)
EMAIL_POLL_INTERVAL=15                 # Segundos entre as conferidas na caixa de entrada (padrão: 15)
EMAIL_HOME_ADDRESS=voce@email.com      # Destino de entrega padrão para jobs de cron

Passo 2: Suba o gateway​

hermes gateway              # Roda em primeiro plano
hermes gateway install      # Instala como serviço de usuário
sudo hermes gateway install --system   # Só no Linux: serviço de sistema no boot

Ao subir, o adaptador:

  1. Testa as conexões IMAP e SMTP
  2. Marca como "lidas" todas as mensagens já existentes na caixa de entrada (só processa e-mails novos)
  3. Começa a consultar por mensagens novas

Como funciona​

Recebimento de mensagens​

O adaptador consulta a caixa de entrada IMAP em busca de mensagens UNSEEN em um intervalo configurável (padrão: 15 segundos). Para cada e-mail novo:

  • A linha de assunto entra como contexto (por exemplo, [Subject: Deploy to production])
  • E-mails de resposta (assunto começando com Re:) pulam o prefixo de assunto — o contexto da conversa já está estabelecido
  • Anexos ficam em cache local:
    • Imagens (JPEG, PNG, GIF, WebP) → disponíveis para a ferramenta de visão
    • Documentos (PDF, ZIP, etc.) → disponíveis para acesso a arquivos
  • E-mails só em HTML têm as tags removidas para extrair o texto puro
  • Mensagens para si mesmo são filtradas, para evitar laços de resposta
  • Remetentes automáticos/noreply são ignorados em silêncio — noreply@, mailer-daemon@, bounce@, no-reply@ e e-mails com os cabeçalhos Auto-Submitted, Precedence: bulk ou List-Unsubscribe

Envio de respostas​

As respostas saem por SMTP com o encadeamento de e-mail correto:

  • Os cabeçalhos In-Reply-To e References mantêm a conversa
  • A linha de assunto é preservada com o prefixo Re: (sem Re: Re: duplicado)
  • O Message-ID é gerado com o domínio do agente
  • As respostas saem como texto puro (UTF-8)

Arquivos anexados​

O agente consegue enviar arquivos anexados nas respostas. Inclua MEDIA:/caminho/do/arquivo na resposta e o arquivo é anexado ao e-mail que sai.

Ignorar anexos​

Para ignorar todos os anexos que chegam (por proteção contra malware ou economia de banda), acrescente ao seu config.yaml:

platforms:
  email:
    skip_attachments: true

Quando isso está ligado, as partes de anexo e embutidas são puladas antes de decodificar o conteúdo. O texto do corpo do e-mail continua sendo processado normalmente.

Controle de acesso​

O acesso por e-mail é mais rígido por padrão do que o das plataformas de conversa:

  1. EMAIL_ALLOWED_USERS definido → só e-mails desses endereços são processados
  2. Sem lista de permissão → remetentes desconhecidos são ignorados em silêncio
  3. EMAIL_ALLOW_ALL_USERS=true → qualquer remetente é aceito (use com cautela)
  4. platforms.email.unauthorized_dm_behavior: pair → remetentes desconhecidos recebem um código de pareamento
aviso

Use uma caixa de entrada dedicada e configure EMAIL_ALLOWED_USERS para a operação normal. O pareamento por e-mail exige adesão explícita porque caixas compartilhadas costumam ter mensagens não lidas sem relação nenhuma, e o Hermes não deveria responder a esses contatos por padrão.

Resolução de problemas​

ProblemaSolução
"IMAP connection failed" ao subirConfira EMAIL_IMAP_HOST e EMAIL_IMAP_PORT. Garanta que o IMAP está habilitado na conta. No Gmail, habilite em Configurações → Encaminhamento e POP/IMAP.
"SMTP connection failed" ao subirConfira EMAIL_SMTP_HOST e EMAIL_SMTP_PORT. Verifique se a sua senha está correta (use a senha de app no Gmail).
Mensagens não chegamVeja se o EMAIL_ALLOWED_USERS inclui o e-mail do remetente. Olhe a pasta de spam — alguns provedores marcam respostas automáticas.
"Authentication failed"No Gmail, você tem que usar uma senha de app, não a sua senha comum. Ative antes a autenticação em duas etapas.
Respostas duplicadasGaranta que só uma instância do gateway está rodando. Confira com hermes gateway status.
Resposta lentaO intervalo de consulta padrão é de 15 segundos. Reduza com EMAIL_POLL_INTERVAL=5 para responder mais rápido (mas com mais conexões IMAP).
Respostas fora da conversaO adaptador usa os cabeçalhos In-Reply-To. Alguns clientes de e-mail (sobretudo os de navegador) podem não encadear direito mensagens automáticas.

Segurança​

aviso

Use uma conta de e-mail dedicada. Não use o seu e-mail pessoal — o agente guarda a senha no .env e tem acesso total à caixa de entrada por IMAP.

  • Use senhas de app no lugar da sua senha principal (obrigatório no Gmail com autenticação em duas etapas)
  • Defina EMAIL_ALLOWED_USERS para restringir quem pode interagir com o agente
  • A senha fica em ~/.hermes/.env — proteja esse arquivo (chmod 600)
  • O IMAP usa SSL (porta 993) e o SMTP usa STARTTLS (porta 587) por padrão — as conexões são criptografadas

Referência de variáveis de ambiente​

VariávelObrigatóriaPadrãoDescrição
EMAIL_ADDRESSSim—Endereço de e-mail do agente
EMAIL_PASSWORDSim—Senha do e-mail ou senha de app
EMAIL_IMAP_HOSTSim—Host do servidor IMAP (por exemplo, imap.gmail.com)
EMAIL_SMTP_HOSTSim—Host do servidor SMTP (por exemplo, smtp.gmail.com)
EMAIL_IMAP_PORTNão993Porta do servidor IMAP
EMAIL_SMTP_PORTNão587Porta do servidor SMTP
EMAIL_POLL_INTERVALNão15Segundos entre as conferidas na caixa de entrada
EMAIL_ALLOWED_USERSNão—Endereços de remetente permitidos, separados por vírgula
EMAIL_HOME_ADDRESSNão—Destino de entrega padrão para jobs de cron
EMAIL_ALLOW_ALL_USERSNãofalseAceita todos os remetentes (não recomendado)