Email Setup

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.

:::info Gateway adapter only: no external dependencies This page covers the Email gateway adapter, which uses Python's built-in imaplib, smtplib, and email modules. No additional packages or external services are required for this gateway path. :::

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.

Prerequisites

• 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

Step 1: Configure Hermes

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 protected]
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 protected],[email protected]

# 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 protected]      # Default delivery target for cron jobs

Step 2: Start the Gateway

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

How It Works

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.

Access Control

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

:::warning Use a dedicated inbox and configure EMAIL_ALLOWED_USERS for normal operation. Email pairing is opt-in because shared inboxes often contain unrelated unread messages, and Hermes should not reply to those contacts by default. :::

Troubleshooting

Security

:::warning Use a dedicated email account. Don't use your personal email — the agent stores the password in .env and has full inbox access via IMAP. :::

• 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

Environment Variables Reference