Email gateway: give Hermes its own inbox

What Email gateway is for

The email adapter turns a dedicated mailbox into a way to talk to Hermes. It polls the inbox over IMAP, works on new mail from allowed senders, and sends threaded plain-text replies over SMTP. It uses only Python's built-in mail libraries, so there is nothing extra to install. Security is strict by default: Hermes acts only on mail whose From domain has been authenticated by your receiving server, and it ignores automated senders and mailing lists. That suits forwarding tasks to your agent by email, or getting scheduled results delivered to a home address.

What you need

• A dedicated email account with IMAP enabled, not your personal inbox
• Use the provider-supported IMAP/SMTP authentication method permitted by your current account or tenant policy. The Hermes docs give app-password examples, but Microsoft 365 tenant support for basic authentication or app passwords is not established here.
• The receiving server's authserv-id (from the topmost Authentication-Results header) for EMAIL_AUTHSERV_ID

Set it up

1. 1

   Run hermes gateway setup and choose Email, or add EMAIL_ADDRESS, EMAIL_PASSWORD, EMAIL_IMAP_HOST, EMAIL_SMTP_HOST and EMAIL_AUTHSERV_ID to ~/.hermes/.env

2. 2

   Set EMAIL_ALLOWED_USERS to the full addresses allowed to send tasks, and optionally EMAIL_HOME_ADDRESS for cron delivery

3. 3

   Start the gateway with hermes gateway or hermes gateway install; on startup it tests IMAP and SMTP and marks existing mail as seen

Check it works

• Startup logs show the IMAP and SMTP connection tests passing
• Send a message from an allowed address and confirm a threaded reply arrives
• Run hermes gateway status to confirm only one gateway instance is running

Limits and failure points

• Without EMAIL_AUTHSERV_ID, mail that needs an authenticated From address is dropped
• Only new mail is processed, replies are plain text, and automated senders such as noreply@ or bulk mail are ignored
• Credentials sit in plaintext in ~/.hermes/.env, and duplicate replies usually mean two gateways are running
• Unknown senders are ignored by default. Pairing is opt-in and still requires authenticated From. An allowlist by itself cannot establish From-header authenticity.

Messaging setup

All messaging platforms

• How to set up Hermes Agent on email

Spotted something wrong or out of date? Tell us on X at @HermesWatcher↗ (opens in a new tab) and we will fix it.