Email

Hermes can receive and reply to emails using standard IMAP and SMTP protocols. Send an email to the agent's address and it replies in-thread — no special client or bot API needed. Works with Gmail, Outlook, Yahoo, Fastmail, or any provider that supports IMAP/SMTP.

This is separate from the bundled Himalaya email skill, which lets the agent manage email through terminal commands and requires the external himalaya CLI plus a Himalaya config file.

---

• A dedicated email account for your Hermes agent (don't use your personal email)
• IMAP enabled on the email account
• An app password if using Gmail or another provider with 2FA

Gmail Setup

1. Enable 2-Factor Authentication on your Google Account
2. Go to App Passwords ↗
3. Create a new App Password (select "Mail" or "Other")
4. Copy the 16-character password — you'll use this instead of your regular password

Outlook / Microsoft 365

1. Go to Security Settings ↗
2. Enable 2FA if not already active
3. Create an App Password under "Additional security options"
4. IMAP host: outlook.office365.com, SMTP host: smtp.office365.com

Other Providers

Most email providers support IMAP/SMTP. Check your provider's documentation for:

• IMAP host and port (usually port 993 with SSL)
• SMTP host and port (usually port 587 with STARTTLS)
• Whether app passwords are required

---

The easiest way:

hermes gateway setup

Select Email from the platform menu. The wizard prompts for your email address, password, IMAP/SMTP hosts, and allowed senders.

Manual Configuration

Add to ~/.hermes/.env:

# Required
EMAIL_ADDRESS=hermes@gmail.com
EMAIL_PASSWORD=abcd efgh ijkl mnop    # App password (not your regular password)
EMAIL_IMAP_HOST=imap.gmail.com
EMAIL_SMTP_HOST=smtp.gmail.com

# Security (recommended)
EMAIL_ALLOWED_USERS=your@email.com,colleague@work.com

# Optional
EMAIL_IMAP_PORT=993                    # Default: 993 (IMAP SSL)
EMAIL_SMTP_PORT=587                    # Default: 587 (SMTP STARTTLS)
EMAIL_POLL_INTERVAL=15                 # Seconds between inbox checks (default: 15)
EMAIL_HOME_ADDRESS=your@email.com      # Default delivery target for cron jobs

---

hermes gateway              # Run in foreground
hermes gateway install      # Install as a user service
sudo hermes gateway install --system   # Linux only: boot-time system service

On startup, the adapter:

1. Tests IMAP and SMTP connections
2. Marks all existing inbox messages as "seen" (only processes new emails)
3. Starts polling for new messages

---

Receiving Messages

The adapter polls the IMAP inbox for UNSEEN messages at a configurable interval (default: 15 seconds). For each new email:

• Subject line is included as context (e.g., [Subject: Deploy to production])
• Reply emails (subject starting with Re:) skip the subject prefix — the thread context is already established
• Attachments are cached locally:
• Images (JPEG, PNG, GIF, WebP) → available to the vision tool
• Documents (PDF, ZIP, etc.) → available for file access
• HTML-only emails have tags stripped for plain text extraction
• Self-messages are filtered out to prevent reply loops
• Automated/noreply senders are silently ignored — noreply@, mailer-daemon@, bounce@, no-reply@, and emails with Auto-Submitted, Precedence: bulk, or List-Unsubscribe headers

Sending Replies

Replies are sent via SMTP with proper email threading:

• In-Reply-To and References headers maintain the thread
• Subject line preserved with Re: prefix (no double Re: Re:)
• Message-ID generated with the agent's domain
• Responses are sent as plain text (UTF-8)

File Attachments

The agent can send file attachments in replies. Include MEDIA:/path/to/file in the response and the file is attached to the outgoing email.

Skipping Attachments

To ignore all incoming attachments (for malware protection or bandwidth savings), add to your config.yaml:

platforms:
  email:
    skip_attachments: true

When enabled, attachment and inline parts are skipped before payload decoding. The email body text is still processed normally.

---

Email access is stricter by default than chat-style platforms:

1. EMAIL_ALLOWED_USERS set → only emails from those addresses are processed
2. No allowlist set → unknown senders are ignored silently
3. EMAIL_ALLOW_ALL_USERS=true → any sender is accepted (use with caution)
4. platforms.email.unauthorized_dm_behavior: pair → unknown senders receive a pairing code

---

---

• Use App Passwords instead of your main password (required for Gmail with 2FA)
• Set EMAIL_ALLOWED_USERS to restrict who can interact with the agent
• The password is stored in ~/.hermes/.env — protect this file (chmod 600)
• IMAP uses SSL (port 993) and SMTP uses STARTTLS (port 587) by default — connections are encrypted

---