How to set up Hermes Agent on email

What you need

The email gateway turns a dedicated inbox into a way to talk to Hermes. IMAP reads incoming mail; SMTP sends replies. This adapter uses Python's built-in mail modules. You do not need the separate Himalaya CLI or mailbox-management skill.

For gateway background, see Hermes Agent messaging gateway explained.

• Hermes installed with a model provider, on a host that stays on when you want replies.
• A dedicated email account with IMAP and SMTP access, its server names, ports and provider-supported password or app password. Use a separate inbox because the agent has full inbox access through IMAP.
• The full email addresses of the people allowed to use it, plus the receiving server's sender-authentication identifier explained below.
• An email account may have provider costs. The Hermes documentation does not require a separate paid email gateway service.

Prepare the dedicated mailbox

Confirm that your provider permits the IMAP/SMTP authentication method this adapter uses. Obtain the server names and ports from that provider. The documented defaults are IMAP over TLS on port 993 and SMTP with STARTTLS on port 587. Both encrypt the connection.

For a Gmail account that permits app passwords, enable 2-Step Verification, open Google app passwords↗ (opens in a new tab) and create an app password for this setup. Copy it when shown and use it instead of your normal Google password. Google says app passwords may be unavailable for organization accounts, Advanced Protection, or security-key-only 2-Step Verification.

If your account does not offer a supported credential, check its provider or administrator's instructions before proceeding. Do not assume an Outlook or Microsoft 365 account accepts app passwords merely because the Hermes page includes that example.

Keep the password secret. Hermes stores it in ~/.hermes/.env. On Unix-like hosts, the email docs recommend restricting that file's permissions with chmod 600.

Choose senders and pin their authentication

Set EMAIL_ALLOWED_USERS to full, comma-separated email addresses. This allowlist restricts who may operate the agent. A bare chat username does not grant access to an email address. Unknown email senders are ignored by default; email pairing is opt-in.

An address in a From field can be forged. Hermes also checks the sender-domain authentication result stamped by your receiving mail server, such as DMARC or aligned SPF/DKIM. An allowlist alone is not enough.

Open the raw source of a message delivered to this inbox. In the topmost Authentication-Results header, find the identifier before the first semicolon. Set EMAIL_AUTHSERV_ID to that exact value. Gmail's documented example is mx.google.com; use your own receiving server's value for another provider.

Confirm with your provider or mail administrator that the receiving server removes incoming headers claiming its own identifier before adding its stamp. A matching string alone does not establish that the header is trustworthy. A self-hosted server needs a stable identifier, not a changing relay hostname.

Without this pin, Hermes drops messages that require authenticated senders. Keep sender authentication enabled and leave EMAIL_ALLOW_ALL_USERS unset. Do not enable EMAIL_TRUST_FROM_HEADER to work around setup errors: that makes Hermes trust the written From address.

Review any existing global allowlist or approved pairings too: the docs say these can also admit senders. Access is to the agent and its configured tools, not just to a mail reply.

Connect it to Hermes

Run the wizard and select Email. It asks for the address, password, server names and allowed senders. Then check ~/.hermes/.env and add the required authentication pin if it is missing.

For manual setup, the Gmail example below shows the required fields and an explicit sender list. Replace the address, password and senders. For another provider, also replace the server names, ports if needed, and authentication identifier. The shown password is a placeholder.

Gateway wizard

hermes gateway setup

~/.hermes/.env (manual Gmail example)

EMAIL_ADDRESS=hermes@gmail.com
EMAIL_PASSWORD=abcd efgh ijkl mnop
EMAIL_IMAP_HOST=imap.gmail.com
EMAIL_SMTP_HOST=smtp.gmail.com
EMAIL_ALLOWED_USERS=your@email.com,colleague@work.com
EMAIL_AUTHSERV_ID=mx.google.com
EMAIL_IMAP_PORT=993
EMAIL_SMTP_PORT=587
EMAIL_POLL_INTERVAL=15

Local relays such as Proton Mail Bridge have different transport settings. Follow the email page's local-relay section if needed. Its certificate-verification exception is limited to loopback hosts, not an instruction to disable checks on remote mail servers.

Start the gateway and send a new email

Before starting, note the documented mailbox change: the adapter marks all existing inbox messages as seen on startup. It then processes new unseen messages. Use the dedicated mailbox, not a personal or shared inbox containing unrelated unread mail.

Start the gateway and watch its IMAP and SMTP connection checks. Once it is listening, send a new, short email from an allowed address to the agent's inbox. The default polling interval is 15 seconds, before model processing and mail delivery time.

Run in the foreground

hermes gateway

Look for receipt in the gateway output and a reply in the sender's mailbox. Reply to that email to check the conversation thread. Ctrl+C stops the foreground gateway.

What it can do

The gateway table lists images, files and threads for email. It does not mark voice, reactions, typing indicators or streaming as supported.

• Incoming image and document attachments are cached locally for the agent's tools. HTML-only email is converted to plain text.
• SMTP replies are plain text, with reply headers to preserve threads. Some mail clients may still display automated replies outside the expected thread.
• The agent can attach files in replies through the documented MEDIA:/path/to/file mechanism.
• Self-messages and automated, bulk or no-reply mail are filtered. A mailing-list message or an email carrying Auto-Submitted, Precedence: bulk or List-Unsubscribe headers is not a suitable first check.

To skip all incoming attachments, merge the following into your existing ~/.hermes/config.yaml. This skips attachment and inline parts before decoding; it still processes body text.

~/.hermes/config.yaml (optional, skip incoming attachments)

platforms:
  email:
    skip_attachments: true

Keep it running

The bot is silent while its computer sleeps or is switched off. Keep the Hermes host awake and online whenever you need replies. A background service does not prevent sleep.

After checking the foreground setup, stop that gateway before installing and starting the background service. The service is systemd on Linux, launchd on macOS, or a logon Scheduled Task on Windows.

Install the gateway service

hermes gateway install

Start it

hermes gateway start

Check it

hermes gateway status

A service cannot answer while its host is asleep or switched off. Do not rely on catching up later: the documented startup behavior marks existing inbox mail as seen. Send a fresh email after restarting to check delivery.

On Windows, Task Scheduler does not restart a gateway that crashes after its launcher exits. Check status if replies stop. See How to run Hermes Agent 24/7 on a VPS or home server for hosting choices.

Only after ordinary replies are behaving as expected, optionally set EMAIL_HOME_ADDRESS in .env to the address that should receive scheduled-task results.

If it doesn't answer

• Connection failure: check both server names and ports, IMAP availability and the provider-supported credential. For Gmail, use the app password and check whether an account password change revoked it.
• No inbound message: send a new email after startup from a full address on the allowlist. Check that it is not filtered as automated mail.
• Unauthenticated From warning: check the exact topmost Authentication-Results identifier, EMAIL_AUTHSERV_ID, and the sender's authentication verdict. An allowed sender can still fail authentication after broken DKIM or forwarding. Fix the authentication problem rather than opening access.
• Missing reply: inspect the sender's spam folder and gateway output. For duplicate replies, check hermes gateway status and make sure only one gateway is running.
• Saved settings but no adapter: check the selected profile and any explicit platforms.email.enabled: false. See Hermes Agent bot not responding in your chat app and Hermes Agent task finished but no message arrived.

Official docs

Reviewed Oct 29, 2026 against the official Hermes docs.

Official Hermes email docs↗ (opens in a new tab)

Related guides

• All messaging platforms
• Hermes Agent messaging gateway explained
• Hermes Agent bot not responding in your chat app
• Hermes Agent task finished but no message arrived
• How to run Hermes Agent 24/7 on a VPS or home server

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

New Hermes Agent updates every day on X. Follow @HermesWatcher