Wiki · Features in depth
Email and calendar
The agent can have an address of its own and access to your calendar. Here is how to set it up, who may write to it and what to watch out for.
Three ways to give the agent email
| Way | What it does | What you need |
|---|---|---|
| Email as a channel (gateway) | You write to an address, the agent replies; works for scheduled jobs too | An address, IMAP and SMTP access, an app password |
| Own address + Himalaya | The agent checks the inbox and sends mail itself, with no always-on bot | A dedicated mail account and the Himalaya tool |
| Google Workspace | Gmail, Calendar, Drive, Sheets, Docs and Contacts | A Google Cloud project and a one-off OAuth sign-in |
If you want email only, pick the channel or Himalaya — that is a matter of minutes. Google Workspace is for the calendar, Drive and Docs, but it needs a Google Cloud project and an approval step.
Email as a channel: setup
Run the wizard and pick Email (it walks you through everything):
❯ hermes gateway setupOr set it by hand in
~/.hermes/.env— four required values:# ~/.hermes/.env EMAIL_ADDRESS=agent@yourdomain.com EMAIL_PASSWORD=app-password # note: not your regular password! EMAIL_IMAP_HOST=imap.yourdomain.com EMAIL_SMTP_HOST=smtp.yourdomain.comAdd who may write to it, plus the receiving server's identity (see below — it is a safety catch):
# who may write to the agent (others are ignored) EMAIL_ALLOWED_USERS=you@yourdomain.com,colleague@company.com # the authserv-id your receiving server stamps into message headers EMAIL_AUTHSERV_ID=mx.google.comKeep it running — in the foreground, or as a service that starts with the machine:
❯ hermes gateway # runs in the foreground ❯ hermes gateway install # as a service
| Value | Default | What it is for |
|---|---|---|
EMAIL_IMAP_PORT | 993 | Receiving mail (encrypted connection) |
EMAIL_SMTP_PORT | 587 | Sending mail |
EMAIL_POLL_INTERVAL | 15 seconds | How often the inbox is checked |
EMAIL_HOME_ADDRESS | — | Where output from scheduled jobs is delivered |
On startup the agent marks every message already in the inbox as seen and processes only new mail. Expect the history to be ignored the first time you start the email channel.
Who may write to the agent
| Setting | What happens |
|---|---|
| An allowlist is set | Only messages from those addresses are processed |
| No allowlist | Unknown senders are silently ignored — they get no reply at all |
Mode pair | An unknown sender receives a pairing code (they can be added) |
Mode decline | An unknown sender gets one polite refusal, then nothing for 24 hours |
Sender authentication: the agent only acts when the server that received the
message confirms that it genuinely came from the stated domain (DMARC or aligned SPF/DKIM). That is
why EMAIL_AUTHSERV_ID exists — it must match exactly what your receiving server writes
into the headers. Without it, the From: header can be forged and the agent would take
orders from a stranger.
Calendar and other Google services
The calendar is not handled through email but through a ready-made Google Workspace workflow, which also covers Gmail, Drive, Sheets, Docs and Contacts. Setup is a one-off and the agent guides you:
- A Google Cloud project is created and the required APIs are enabled (Gmail, Calendar, Drive, Sheets, Docs, Contacts).
- Desktop-app OAuth credentials are created and the client secret file is downloaded.
- The agent generates a sign-in URL — you approve it in the browser and paste the redirect URL back.
- From then on the token refreshes itself.
Working with the calendar then looks like this (you just ask in the conversation):
Watch the timezone. The calendar requires a timezone offset
(+02:00 for Czech summer time, for example) or a UTC time. When the offset is missing,
the time is taken as UTC — and your meeting lands two hours off.
Pitfalls from our systems
| What happened | What to do |
|---|---|
| The agent processed no messages | Usually EMAIL_AUTHSERV_ID does not match what your server writes, or the address is not on the allowlist. Both show up in the service log |
| Replies never arrived | With your own domain, SPF, DKIM and DMARC must be correct. Without them mail lands in spam or is dropped |
| The agent obeyed a stranger | Never use an "allow everyone" mode. The allowlist is what protects you |
| Sign-in stopped working after a password change | The app password must be updated in the settings too — some providers make you generate a new one |
| A meeting was booked two hours off | The timezone offset was missing. Always state the time with its offset, or ask how the agent understood it before writing |
| Hundreds of old emails sat in the inbox and the agent ignored them | That is correct — history is marked as seen at startup. Forward an older message again if you need it handled |
Our tips
| Tip | Why |
|---|---|
| Give the agent an address of its own | It stays out of your work mail and you keep a clear allowlist |
| Write a meaningful subject | The agent recognises the task better and you keep threads readable |
| Treat email like a letter, not a chat | It is more public and slower — sensitive things belong in chat or the terminal |
| Send scheduled jobs to one address | Set EMAIL_HOME_ADDRESS and your morning digests arrive reliably |
| Try one email before rolling it out | You verify sender authentication and replies before building on it |