Skip to main content
Install openmailsh/hermes-plugin and mail to the agent’s address wakes it. Replies go out in the same thread.

​
Before you start

  • Hermes Agent, installed and working.
  • An OpenMail API key from the console. Any scope works.

​
Install

1

Install the plugin

2

Run setup

Paste the key. Setup picks your inbox, or creates one.
3

Start the gateway

Already running? hermes gateway restart. Look for [OpenMail] Connected as <address> in the log.
Email the agent and it answers in the thread. Or ask it on your usual chat:
  • “What’s in the inbox since this morning?”
  • “Reply to Marc that Thursday works, and cc Jonas.”
  • “Sign up for the Linear newsletter and give me the confirmation code.”
Something off? hermes openmail doctor.

​
Modes

Setup picks channel. Change it with OPENMAIL_MODE in ~/.hermes/.env, or per inbox. notify needs a home channel: hermes gateway setup. Only mail from a person gets a reply. Notifications and verification codes reach the agent as information, so it never answers noreply@. Spam never reaches it.

​
Who can email the agent

Anyone, by default. Restrict it under Allow/Block List in the console or with the CLI:
Blocked mail is dropped on the server; the agent never sees it. Hermes’s own GATEWAY_ALLOWED_USERS applies too.

​
Prompt injection

Replies go to the sender OpenMail recorded, not one the message claims. The model never sees the API key. Inbound mail can’t issue gateway commands. The agent can still start new threads; to stop that, make the inbox’s outbound policy an allowlist.

​
What the agent can do

Tools default to the agent’s own inbox. The bundled openmail skill teaches it the CLI for everything else; install the CLI separately.

​
Several inboxes

Say yes when setup offers the whole pod, and the agent runs every inbox in it, including ones it creates later. Each sender gets a conversation per inbox; replies leave from the inbox that received the mail. Set modes per inbox in ~/.hermes/config.yaml:

​
Subagents and Bots

With a pod key, the agent can create an inbox, mint a key for it, and hand it to a child. delegate_task children inherit the parent’s setup and can do this themselves. Give each Bot its own inbox key and it runs as its own address.

​
Attachments

Text from PDF, DOCX, XLSX, PPTX, CSV, and images (OCR) reaches the agent inline, up to 8k characters per file and 24k total. Files without text arrive as files, so a vision model sees the picture. Outbound, the agent attaches local files by path.

​
Scheduled jobs

--deliver openmail on a cron job emails its output to you; --deliver openmail:alice@x.com to anyone. Works with the gateway stopped.

​
Reliability

A restart replays missed mail and keeps replies in-thread. A rejected key stops the plugin instead of retrying; hermes openmail doctor says why.

​
Configuration reference

Setup writes ~/.hermes/.env. If you gave it an account key, it stores a narrower pod key instead. Each variable also works under platforms.openmail in config.yaml, lower-cased without the prefix. Skipping setup? OPENMAIL_API_KEY and OPENMAIL_ALLOW_ALL_USERS=true are enough. Scripted: hermes openmail setup --api-key <key> -y, or --api-key-stdin.