| --- |
| sidebar_position: 7 |
| title: "Email" |
| description: "Set up Hermes Agent as an email assistant via IMAP/SMTP" |
| --- |
| |
| # 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 No External Dependencies |
| The Email adapter uses Python's built-in `imaplib`, `smtplib`, and `email` modules. No additional packages or external services are required. |
| ::: |
|
|
| --- |
|
|
| ## 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](https://myaccount.google.com/apppasswords) |
| 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](https://account.microsoft.com/security) |
| 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: |
|
|
| ```bash |
| 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`: |
|
|
| ```bash |
| # 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 |
| ``` |
|
|
| --- |
|
|
| ## Step 2: Start the Gateway |
|
|
| ```bash |
| 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`: |
|
|
| ```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 follows the same pattern as all other Hermes platforms: |
|
|
| 1. **`EMAIL_ALLOWED_USERS` set** → only emails from those addresses are processed |
| 2. **No allowlist set** → unknown senders get a pairing code |
| 3. **`EMAIL_ALLOW_ALL_USERS=true`** → any sender is accepted (use with caution) |
| |
| :::warning |
| **Always configure `EMAIL_ALLOWED_USERS`.** Without it, anyone who knows the agent's email address could send commands. The agent has terminal access by default. |
| ::: |
| |
| --- |
| |
| ## Troubleshooting |
| |
| | Problem | Solution | |
| |---------|----------| |
| | **"IMAP connection failed"** at startup | Verify `EMAIL_IMAP_HOST` and `EMAIL_IMAP_PORT`. Ensure IMAP is enabled on the account. For Gmail, enable it in Settings → Forwarding and POP/IMAP. | |
| | **"SMTP connection failed"** at startup | Verify `EMAIL_SMTP_HOST` and `EMAIL_SMTP_PORT`. Check that your password is correct (use App Password for Gmail). | |
| | **Messages not received** | Check `EMAIL_ALLOWED_USERS` includes the sender's email. Check spam folder — some providers flag automated replies. | |
| | **"Authentication failed"** | For Gmail, you must use an App Password, not your regular password. Ensure 2FA is enabled first. | |
| | **Duplicate replies** | Ensure only one gateway instance is running. Check `hermes gateway status`. | |
| | **Slow response** | The default poll interval is 15 seconds. Reduce with `EMAIL_POLL_INTERVAL=5` for faster response (but more IMAP connections). | |
| | **Replies not threading** | The adapter uses In-Reply-To headers. Some email clients (especially web-based) may not thread correctly with automated messages. | |
| |
| --- |
| |
| ## 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 |
| |
| | Variable | Required | Default | Description | |
| |----------|----------|---------|-------------| |
| | `EMAIL_ADDRESS` | Yes | — | Agent's email address | |
| | `EMAIL_PASSWORD` | Yes | — | Email password or app password | |
| | `EMAIL_IMAP_HOST` | Yes | — | IMAP server host (e.g., `imap.gmail.com`) | |
| | `EMAIL_SMTP_HOST` | Yes | — | SMTP server host (e.g., `smtp.gmail.com`) | |
| | `EMAIL_IMAP_PORT` | No | `993` | IMAP server port | |
| | `EMAIL_SMTP_PORT` | No | `587` | SMTP server port | |
| | `EMAIL_POLL_INTERVAL` | No | `15` | Seconds between inbox checks | |
| | `EMAIL_ALLOWED_USERS` | No | — | Comma-separated allowed sender addresses | |
| | `EMAIL_HOME_ADDRESS` | No | — | Default delivery target for cron jobs | |
| | `EMAIL_ALLOW_ALL_USERS` | No | `false` | Allow all senders (not recommended) | |
| |
