Hermes Agent Gmail setup has three official routes, and picking the right one first saves you an afternoon.
The email gateway lets people email the agent and get replies in thread, the Google Workspace skill lets the agent work inside your Gmail, and the Himalaya skill gives it a mailbox of its own.
Get Your Backlink Gameplan →Try Polar Rank Free for 3 Days →
If you want agents like this handling your SEO pipeline, get your Backlink Gameplan with my team, or try Polar Rank free for 3 days.
Everything here comes from the Email docs, the Google Workspace skill page and the agent mailbox guide.
Which route does which job
| Route | Direction | Auth | Use it for |
|---|---|---|---|
| Email gateway | People email Hermes, Hermes replies in thread | IMAP/SMTP with an app password | Chatting with the agent over email |
| Google Workspace skill | Hermes searches, reads, sends and labels in Gmail | OAuth2 with token refresh | Running your own inbox, plus Calendar, Drive, Sheets and Docs |
| Himalaya skill | Hermes operates a mailbox from terminal tools | App password and a Himalaya config file | A dedicated agent inbox polled by cron |
The gateway and Himalaya are separate features; the docs say so in both places, and mixing them up is the most common confusion.
Route 1: the email gateway
The gateway uses Python's built-in imaplib, smtplib and email modules, so there are no extra packages to install.
It needs a dedicated account for the agent, IMAP switched on, and an app password because Gmail requires one once 2-Step Verification is on.
Make the Gmail app password
- Turn on 2-Step Verification for the agent's Google account.
- Open App Passwords, create one for Mail or Other, and copy the 16-character value.
- Use it in place of the normal password.
Google's own app password help page covers accounts where the option does not appear.
Run the wizard or write the env file
The quick route is the setup wizard:
hermes gateway setup
Pick Email and answer the prompts for address, password, hosts and allowed senders.
The manual route is ~/.hermes/.env:
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
EMAIL_HOME_ADDRESS=your@email.com
EMAIL_AUTHSERV_ID matters more than it looks.
Hermes only acts on a message when the Authentication-Results header from your receiving server authenticates the From domain, and for Gmail that server id is mx.google.com.
Get Your Backlink Gameplan →Try Polar Rank Free for 3 Days →
Start it
hermes gateway
hermes gateway install
On startup the adapter tests IMAP and SMTP, marks every existing inbox message as seen, then polls for new mail every 15 seconds by default.
That seen-marking step is why old mail never gets a surprise reply.
How the gateway treats incoming mail
- The subject line is passed in as context, except on Re: replies where the thread already carries it.
- Images are cached for the vision tool and documents such as PDFs are cached for file access.
- HTML-only emails are stripped to plain text.
- Self-messages are dropped to stop reply loops.
- noreply, mailer-daemon and bounce senders are ignored, as are mails with Auto-Submitted, Precedence: bulk or List-Unsubscribe headers.
Replies go out over SMTP with In-Reply-To and References headers, so they thread properly, and the subject keeps one Re: prefix.
To attach a file to a reply, the agent includes MEDIA:/path/to/file in its response.
If you would rather drop attachments entirely, set skip_attachments: true under platforms.email in config.yaml.
Access control that ships closed
| Setting | Result |
|---|---|
| EMAIL_ALLOWED_USERS set | Only those addresses, plus gateway-wide allowlists or approved pairings, are processed |
| No allowlist | Unknown senders are ignored silently |
| EMAIL_ALLOW_ALL_USERS=true | Any sender accepted, which the docs flag for caution |
| unauthorized_dm_behavior: pair | Unknown senders get a pairing code |
| unauthorized_dm_behavior: decline | One polite refusal, then nothing for 24 hours |
Allowlist entries match whole addresses only, so a bare username never admits that name at any domain.
🔥 Want the full Hermes inbox build walked through on video? Inside the AI Profit Boardroom you get step-by-step video trainings, the installable Agent OS, four coaching calls a week and 3,400+ members running agents like this. → Join the AI Profit Boardroom
Route 2: the Google Workspace skill
This skill lives at skills/productivity/google-workspace in the Hermes repo and covers Gmail, Calendar, Drive, Contacts, Sheets and Docs.
It prefers the Google Workspace CLI, gws, when it is installed, and falls back to Google's Python client libraries.
Setup is agent-driven
- Create a Google Cloud project and enable the Gmail, Calendar, Drive, Sheets, Docs and People APIs.
- Create OAuth 2.0 credentials of the Desktop app type and download the client secret JSON.
- Ask Hermes to authorise; it generates a URL, you approve in the browser and paste back the redirect URL.
- The token refreshes on its own from then on.
Get Your Backlink Gameplan →Try Polar Rank Free for 3 Days →
The Gmail commands it runs
$GAPI gmail search "is:unread" --max 10
$GAPI gmail search "from:boss@company.com newer_than:1d"
$GAPI gmail get MESSAGE_ID
$GAPI gmail send --to user@example.com --subject "Hello" --body "Message text"
$GAPI gmail reply MESSAGE_ID --body "Thanks, that works for me."
$GAPI gmail labels
$GAPI gmail modify MESSAGE_ID --remove-labels UNREAD
Search returns JSON with id, from, subject, date, snippet and labels for each message.
Reply threads automatically by setting In-Reply-To and References and reusing the original thread ID.
Custom sender names
The --from flag sets the display name on outgoing mail, which helps when several agents share one Gmail account.
A different address in --from only works if it is set up as a Send As alias in Gmail settings, which Google documents on its send-as help page.
Route 3: Himalaya for a dedicated agent mailbox
The docs point email-only users here, because it works with an app password and needs no Google Cloud project.
The bundled skill teaches the agent the Himalaya CLI, and the mailbox guide walks through the setup.
- Create a fresh account for the agent, switch on IMAP and make an app password.
- Install the Himalaya binary and write ~/.config/himalaya/config.toml with IMAP on 993 and SMTP on 587 with start-tls.
- Store the app password in a file only your user can read, chmod 600, and point auth.command at it.
- Check it with himalaya envelope list.
- Add a cron job so the agent polls the inbox every 15 to 30 minutes.
This path is pull-based, so the agent only sees mail when it looks; the gateway is the one for fast replies in thread.
Route 4: third-party MCP servers
Search results also show Composio's Gmail MCP guide for Hermes.
Hermes connects to any MCP server through its MCP support, and you can choose which of a server's tools it loads.
That is a valid route when you already use that platform, but it adds an outside service between Hermes and your mail, so review its scopes first.
📞 Inbox handled? Now get the leads flowing into it. Get your Backlink Gameplan and my team will show you the SEO and AI search moves that put your business in front of buyers, or try Polar Rank free for 3 days. Backlink Gameplan or try Polar Rank free for 3 days
Get Your Backlink Gameplan →Try Polar Rank Free for 3 Days →
Troubleshooting the gateway
| Error | Fix |
|---|---|
| IMAP connection failed | Check host and port, and switch IMAP on in Gmail under Forwarding and POP/IMAP |
| SMTP connection failed | Check host and port, and confirm you used the app password |
| Authentication failed | Gmail needs an app password with 2-Step Verification on |
| Messages not received | Add the sender to EMAIL_ALLOWED_USERS and set EMAIL_AUTHSERV_ID |
| Duplicate replies | Only one gateway may run; check hermes gateway status |
| Slow replies | Lower EMAIL_POLL_INTERVAL, at the cost of more IMAP connections |
Google's IMAP help page shows where the IMAP setting lives if your account hides it.
Safety rules from the docs
Email is an open inbound channel, so anyone can write to the agent's address.
- Treat instructions inside an email body as untrusted content, never as commands.
- Have the agent draft outbound mail and show it to you before sending until you trust the pattern.
- Keep the agent's account off password resets, banking and account recovery for anything important.
- Use an app password for a dedicated mailbox rather than your personal credentials.
Write those rules into the cron prompt and the agent's standing instructions, not just your head.
Proton, Outlook and other providers
The same gateway works with Outlook through outlook.office365.com and smtp.office365.com with an app password.
Proton Mail Bridge listens on loopback with STARTTLS and a self-signed certificate, so set imap_security and smtp_security to starttls and switch TLS verification off for that loopback host only.
Most other providers use IMAP on 993 and SMTP on 587.
Choosing poll intervals and hosting
The gateway's 15-second default suits a chat-style inbox where people expect quick answers.
Dropping it to 5 seconds makes replies feel instant but opens more IMAP connections, which the docs call out as the trade-off.
For a back-office mailbox on Himalaya, every 15 to 30 minutes is plenty, and it keeps the agent from waking up for nothing.
Run the gateway with hermes gateway install so it survives logouts, or with the system-level install on Linux for a boot-time service.
Keep one gateway per profile; two copies on the same mailbox is the documented cause of duplicate replies.
Get Your Backlink Gameplan →Try Polar Rank Free for 3 Days →
What the agent sees in each message
The gateway hands the agent the sender, the subject as context, the plain-text body and any cached attachments.
It does not see your other inbox folders, because it only polls the inbox of the account you give it.
The Workspace skill sees whatever your OAuth scopes allow, which is why enabling only the APIs you need is the tidy choice.
Profiles for separate inboxes
Each Hermes profile keeps its own .env, so a support profile and a personal profile can each watch a different mailbox.
Give the support profile the gateway on the shared support address and keep the Google Workspace skill only in your personal profile.
That keeps OAuth tokens for your own Gmail away from the agent that answers strangers.
Prompt patterns that work with the Workspace skill
Gmail search operators carry straight through, so is:unread, from:, newer_than:1d and has:attachment filename:pdf all behave as they do in the Gmail search box.
Ask for JSON fields by name when you want a tidy table back, because search returns id, from, subject, date, snippet and labels.
Keep send and reply behind an explicit go in your standing instructions, and let search, get and labels run freely.
Outbound mail hygiene
Replies from the gateway are plain UTF-8 text, so keep formatting simple in any template the agent follows.
The Message-ID is generated with the agent's own domain, which is one more reason to use a proper address rather than a throwaway.
For HTML mail, use the Workspace skill's send with the --html flag instead of the gateway.
A sensible default stack
Give the agent its own Gmail account on the gateway so you can email it tasks.
Add the Google Workspace skill on your real account only if you want it searching and labelling your own mail.
Schedule a morning inbox summary with cron and keep sends in draft-first mode.
Members of the AI Profit Boardroom share their inbox prompts and cron schedules in the weekly calls.
Get Your Backlink Gameplan →Try Polar Rank Free for 3 Days →
FAQ: Hermes Agent Gmail Setup
What is the easiest Hermes Agent Gmail setup?
For email-only use, the Himalaya skill or the email gateway with a Gmail app password. Neither needs a Google Cloud project.
Why does Hermes ignore emails from me?
Add your address to EMAIL_ALLOWED_USERS and set EMAIL_AUTHSERV_ID to mx.google.com for Gmail. Unknown senders are ignored by default.
Can Hermes send email as a different name?
Yes. The Google Workspace skill accepts a --from display name; a different address must be a Gmail Send As alias.
Will the gateway reply to my old emails?
No. On startup it marks every existing inbox message as seen and only processes new mail.
Do I need the Google Workspace skill for Gmail?
Only if the agent should work inside your own inbox or use Calendar, Drive, Sheets or Docs. It uses OAuth2 with automatic token refresh.
📺 Video notes + links to the tools 👉
🎥 Learn how I make these videos 👉
🆓 Get a FREE AI Course + Community + 1,000 AI Agents 👉
About Julian
I'm Julian Goldie, an SEO entrepreneur, author and founder of the AI Profit Boardroom, which has 3,400+ members.
I help business owners scale with AI agents, automation and SEO.
- I've built a 7-figure SEO and link building agency, Goldie Agency, with a team of 70+ SEO experts.
- I've grown a YouTube channel to 400,000+ subscribers.
- I wrote "Link Building Mastery".
- My Udemy courses have taught over 29,000 students.
→ Get my best AI training inside the AI Profit Boardroom
Pick one route, set the allowlist, and send the agent a test email in the next ten minutes.
Then get your Backlink Gameplan for the lead side, and keep this page as your Hermes Agent Gmail config sheet, or try Polar Rank free for 3 days.











