.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
Email gets undersold as an agent channel. People assume it's slow, formal and not worth wiring up when Telegram exists. They're missing the point. Email is the channel that handles forwarded receipts, automated reports, alerts from other systems and anything where you want a paper trail. An agent that reads your inbox is a much more interesting one than an agent that just answers DMs.
This guide covers the IMAP/SMTP setup for Hermes, the Gmail-specific app password dance you need until OAuth lands and the inbox filtering patterns that keep the agent from drowning when your inbox gets noisy.
Pick a dedicated email account first
Same advice as for WhatsApp: don't point the agent at your personal email. Three reasons.
The agent will read every incoming message, which means every message goes through your LLM provider. Your bank statements, your therapist's appointment confirmations, your dad's reply about Christmas plans. Even if the LLM provider is reputable, that's a privacy posture you don't want.
The agent will reply to messages it thinks merit a reply. By default, only to senders on your allowlist, but configuration mistakes happen. You don't want a misconfigured agent auto-replying to a real human you also email manually.
Email accounts are easier to lock down when they're dedicated. You can give the agent's account narrower OAuth scopes, route only specific senders to it via forwarding rules, even put it behind a separate domain so the bot's email address looks like a bot.
Get a fresh free account (Gmail, ProtonMail, FastMail, your own Postfix install if you're feeling ambitious). Use it only for the agent.
Gmail with app passwords
Gmail is the most common email backend for Hermes setups and Google's app-password flow is what you'll use until OAuth support lands.
Enable 2-Step Verification on the Google account first. App passwords aren't available without it. Go to myaccount.google.com, Security, 2-Step Verification, set it up.
Then visit myaccount.google.com/apppasswords directly. Generate an app password named something like "Hermes Agent". Google shows the password once; copy it now or you'll have to regenerate.
The app password is a 16-character string with no spaces (Google displays it with spaces for readability; strip them). It substitutes for your normal password in IMAP/SMTP auth.
In ~/.hermes/.env:
[email protected]
EMAIL_PASSWORD=abcd1234efgh5678
EMAIL_IMAP_HOST=imap.gmail.com
EMAIL_IMAP_PORT=993
EMAIL_SMTP_HOST=smtp.gmail.com
EMAIL_SMTP_PORT=465The 16-character app password goes into EMAIL_PASSWORD. Don't put your real Google account password there; it won't work even if 2FA is off, because Google requires app passwords for IMAP/SMTP access from third-party apps.
Set the allowed senders:
hermes config set messaging.email.allowed_senders '["[email protected]", "[email protected]"]'The agent will read all incoming messages but only respond to ones from senders on this list. Messages from anyone else are silently ignored (or filed to a folder, depending on your messaging.email.unknown_sender_action setting).
Configure the polling interval:
hermes config set messaging.email.poll_interval_seconds 6060 seconds is a sensible default. The bot checks for new messages every minute. Drop to 30 if you want faster response times; raise to 300 if you want fewer round-trips to the IMAP server.
Run the gateway:
hermes gateway startSend the bot a test email from a sender on your allowlist. Within a minute, you should see a reply.
Other Gmail-flavoured providers
Several providers use Gmail-compatible IMAP/SMTP with their own hostnames:
Google Workspace: same hostnames as gmail.com, but use your Workspace email address.
FastMail: imap.fastmail.com:993, smtp.fastmail.com:465. App passwords via www.fastmail.com/settings/security.
ProtonMail: requires the Proton Mail Bridge running locally; once installed, the bridge exposes 127.0.0.1:1143 and 127.0.0.1:1025. The setup is more involved; the Hermes docs have the specific config snippet.
Apple iCloud Mail: imap.mail.me.com:993 with app-specific password. Apple requires 2FA on the Apple ID.
Self-hosted Postfix/Dovecot: whatever your server's TLS-enabled IMAP/SMTP ports are. The advantage of self-hosted is no third-party rate limits and no app-password dance; the disadvantage is you're now running an email server.
Inbox filters and folders
Out of the box, the agent reads everything from the INBOX folder. For a noisy inbox, you'll want to either filter at the email-server side or configure the agent to only read certain folders.
Server-side filtering, in Gmail: create filters that route specific senders to specific labels. The agent ignores anything not in INBOX (or whatever folder you've configured). Forward only the senders you want to give the agent attention to.
Hermes-side filtering, more flexible:
messaging:
email:
folders_to_poll: ["INBOX", "Agent-Tasks"]
folders_to_ignore: ["Spam", "Promotions"]
sender_patterns:
- match: "*@github.com"
action: respond
- match: "*@example.com"
action: respond
- match: "newsletter@*"
action: ignoreThe patterns are evaluated in order; first match wins. Useful when you want the agent to handle GitHub notifications, work emails and personal mail differently.
What the agent does with email
By default, the agent treats each incoming email as a user message and replies in-thread (preserving the message-id headers so reply chains stay threaded in your client). The reply goes to the original sender; if the email was sent to multiple people, the bot replies only to the sender unless you configure reply-all behaviour.
For long emails (forwarded reports, document attachments), the agent reads the whole message including attachments. Attachments are saved to ~/.hermes/inbox/email/<message-id>/ for the agent to access via filesystem tools. PDFs get extracted to text via the Hermes PDF skill if it's enabled. Images get sent to vision-capable models.
For automated emails (alerts from monitoring systems, build notifications), you usually don't want the agent to reply at all. Configure no-reply behaviour for those:
messaging:
email:
no_reply_patterns:
- "noreply@*"
- "alerts@*"
- "notifications@*"The agent still reads these and stores them in memory but doesn't generate a response. Useful for ingesting alerts the agent should know about without spamming the alert sender with replies.
SMTP rate limits and Gmail-specific gotchas
Gmail's SMTP server has a 500 messages per day per account limit on free accounts and 2000 on Workspace. For most personal agents, this is plenty (a typical bot sends a few dozen messages a day). For a busy bot, watch out.
Gmail also has a 100-recipient-per-message limit. If your agent ever generates a multi-recipient email, the SMTP send fails with a 552 error. Hermes splits large recipient lists automatically, but it's worth knowing about.
If you hit Gmail's limits, the failure mode is "send temporarily blocked"; you typically get a few hours' cooldown before sends work again. Don't retry aggressively or Google may flag the account.
Outbound-only configurations
Sometimes you want the agent to send emails (a daily summary, an alert) without exposing it to incoming mail. Configure SMTP only:
messaging:
email:
mode: outbound_only
smtp_host: smtp.gmail.com
smtp_port: 465
smtp_user: [email protected]
smtp_password: "your-app-password"
from_address: "Hermes Bot <[email protected]>"The agent can call the send_email tool from any skill or chat session. Useful for sending nightly reports to yourself based on what the agent saw during the day or for routing async results from long-running tasks back to your inbox.
Troubleshooting
If the agent never sees any incoming messages despite emails arriving in the inbox, check IMAP connectivity:
openssl s_client -connect imap.gmail.com:993 -crlf
# After connection, type:
a1 LOGIN [email protected] your-app-passwordIf LOGIN succeeds with an "OK" response, your credentials are right. If it fails, the password is wrong (most likely, the spaces in your app password didn't get stripped before pasting).
If IMAP works but the agent still doesn't process incoming mail, check the polling interval and the folders_to_poll config. The default is INBOX; if you've moved emails to a different label and Gmail's "Inbox" no longer includes them, the agent doesn't see them.
If outbound mail goes out but the recipient never gets it, check Gmail's "Sent" folder via the web UI. If it's not there, the SMTP send failed silently (rare). If it is there, the recipient's mail server is rejecting it; check spam folders. Bot-generated email goes to spam more often than human email; SPF, DKIM and DMARC records on your sending domain help if you have a custom domain.
Email plus the other channels
Email pairs nicely with chat platforms via the channel-routing patterns covered in the multi-platform gateway article. Common patterns:
Forward an email to the agent, get a Telegram reply with the summary. The agent reads the email, processes it, replies via your preferred chat channel. Useful for quick triage of forwarded items.
Ask the agent on Telegram to draft an email, the agent generates the message and sends it via SMTP. Useful for "send a polite refusal to that intern who keeps emailing me about their startup".
Cron skills that pull data from one source and email a report on a schedule. The agent runs the cron, generates the email, sends it. The OpenClaw cron scheduler guide covers the equivalent on the OpenClaw side; Hermes uses the same general pattern.
If you'd like the install done for you
The LumaDock Hermes Agent VPS template ships with the IMAP/SMTP libraries pre-installed; you only need to drop your credentials into .env and configure folders. The default settings handle Gmail and most third-party hosts without further tuning.
