MailGate

An air-gapped secure email intermediary for Gmail. MailGate exposes a small local REST API that gives an AI agent (or any program) full email capabilities — read, search, reply, send, trash, mark read/unread — while strictly isolating credentials and redacting all OTP / 2FA / password-reset / security verification messages so they can never leak into an agent's context.

Built for Hermes Agent but usable by any program that can speak HTTP.

See the release notes for recent changes.

Why

Giving an LLM agent raw access to a Gmail inbox is dangerous: one-time passwords, 2FA codes, and password-reset links are exactly the kind of high-value secrets that should never enter a model's context window. MailGate sits between the agent and Gmail and enforces a hard policy:

1. Zero credential exposure — the Gmail App Password and the local API token live only in the macOS Keychain, or — with explicit confirmation, on non-macOS / SSH sessions — in a plaintext 0600 file. They are never placed in .env files and never returned by any API response.
2. Deterministic OTP airgap — messages matching security rules are intercepted before the agent sees them: excluded from list/search views (or returned masked as [REDACTED]), and hard-blocked on read.
3. Protected mutations — the agent cannot reply to, delete, trash, or change the read status of a flagged security/OTP message.

Architecture

Agent ──HTTP──▶ MailGate (FastAPI, 127.0.0.1:8765) ──IMAP/SMTP──▶ Gmail
                    │
                    ├─ macOS Keychain (or 0600 file) — App Password + API token
                    └─ Sensitive-email classifier (regex + sender domains)

• Runtime: Python 3.11+, FastAPI, Uvicorn
• Email: IMAP (imapclient) for read/search/trash and read status, SMTP (smtplib) for send/reply, over TLS with a Gmail App Password
• Credentials: macOS Keychain via the security CLI, with a portable 0600 file fallback (~/.hermes/mailgate/credentials.json)
• Service: launchd plist for background execution

Install

git clone https://github.com/philbird/mailgate.git
cd mailgate
uv sync --extra dev        # or: python -m venv .venv && .venv/bin/pip install -e '.[dev]'

Provision credentials

Create a Gmail App Password (not your account password) at https://myaccount.google.com/apppasswords, then run:

mailgate-provision --email you@gmail.com

It prompts for the App Password (hidden input), stores the address, App Password, and a fresh API token, then prints the token. Credentials go to the macOS Keychain when writable; otherwise (SSH sessions, Linux) it warns and asks for confirmation before falling back to a plaintext 0600 file, which any process running as your user can read. Force a backend with --backend keychain|file|auto (default auto). The token is never returned by the API — copy it into your agent's secure config.

To rotate the token or change the account, just re-run the command.

Run

mailgate                 # serves on 127.0.0.1:8765

Or install the launchd service (edit the paths in the plist first):

cp launchd/com.hermes.mailgate.plist ~/Library/LaunchAgents/
launchctl load ~/Library/LaunchAgents/com.hermes.mailgate.plist

Client CLI

mailgate-api is the agent-safe client: it reads the API token from the credential store at call time and attaches it automatically, so the token never lands in .env, memory, or an agent's working context.

mailgate-api list                     # latest messages (readable table)
mailgate-api list --unread --limit 10
mailgate-api list --json              # machine-readable JSON
mailgate-api search "from:foo@bar.com"
mailgate-api read <message_id>        # full body (403 if sensitive)
mailgate-api mark-read <message_id>   # mark as read (403 if sensitive)
mailgate-api mark-unread <message_id> # mark as unread (403 if sensitive)
mailgate-api send --to a@b.c --subject "Hi" --body "Hello"
mailgate-api send --to a@b.c --subject "Hi" --body-file notes.md
mailgate-api reply <message_id> --body "Thanks" [--reply-all]
mailgate-api trash <message_id>       # move to Trash (403 if sensitive)
mailgate-api healthz
mailgate-api token                    # print the token (rarely needed)

send/reply accept --body, --body-file, or --body - (stdin). list/read/search accept --json for machine-readable output. Readable list and read output includes the message's read status. Fetching messages uses IMAP PEEK and leaves that status unchanged; use mark-read or mark-unread to change it explicitly.

API

All endpoints (except /healthz) require an Authorization: Bearer <token> token.

Method	Path	Description
GET	/v1/messages	Search/list. Params: query (Gmail syntax), unread_only, limit, offset. Sensitive messages are returned masked (is_redacted: true).
GET	/v1/messages/{id}	Full message (HTML/plain → Markdown). 403 if sensitive.
PATCH	/v1/messages/{id}	Set read status. Body {"is_read": true} or {"is_read": false} (required boolean). 403 if sensitive; 404 if missing.
POST	/v1/messages/{id}/reply	Reply to a thread. Body {"body": "...", "reply_all": false}. 403 if the thread is sensitive.
POST	/v1/messages/send	Send. Body {"to": [...], "subject": "...", "body": "..."}.
DELETE	/v1/messages/{id}	Move to Trash. 403 if sensitive.
GET	/healthz	Liveness check (no auth).

Message IDs are positive Gmail IMAP UIDs in the inbox. List and full-message responses include is_read, a boolean; masked messages retain this field. Updating read status returns {"status": "updated", "id": "12345", "is_read": true} (or false when marking unread). Strings and numbers are not accepted for is_read.

Examples

curl -H "Authorization: Bearer $TOKEN" \
  "http://127.0.0.1:8765/v1/messages?unread_only=true&limit=10"

# Mark a message as read; use false to mark it unread.
curl -X PATCH -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"is_read": true}' "http://127.0.0.1:8765/v1/messages/12345"

Sensitive-email classification

A message is SENSITIVE_LOCKED if it matches any rule:

A. Subject/body regex (case-insensitive)

• otp, 2fa, mfa, verification code, security code, one-time passcode, passcode
• password reset, reset your password, confirm your email, verify your account
• sign-in attempt, new login from, authorization code, login verification
• standalone 4–8 digit codes: your code is 123456, code: 482910

B. High-risk sender domains (always blocked)

• accounts.google.com, appleid.apple.com, auth0.com, okta.com, paypal.com, stripe.com — extend the list in mailgate/classifier.py for banks/exchanges.

github.com is intentionally not always-blocked (it sends lots of non-security mail). GitHub auth alerts are still caught by the wording regexes ("New sign-in to your account", etc.).

The classifier is deliberately conservative — over-blocking is safer than leaking a one-time password. Rules are plain data at the top of mailgate/classifier.py, trivial to audit and extend.

Security notes

• The service binds to 127.0.0.1 only. Do not expose it publicly.
• Credentials are stored in the macOS Keychain under service mailgate (accounts gmail-address, gmail-app-password, api-token).
• List-view classification uses the subject + first ~4 KB of the text body; the read endpoint re-classifies on the full body as a backstop, so a code buried deep in a message is still blocked on read.
• Token comparison is constant-time (hmac.compare_digest).

Development

uv run pytest

Hermes skill

A ready-to-install Hermes Agent skill lives at skills/mailgate/SKILL.md — see skills/README.md for one-command install.

License

MIT