Overview

AgentMail is a YC-backed (W25), SOC 2 Type II certified API-first email platform designed specifically for AI agents. Unlike traditional email (Gmail, Outlook) where the agent borrows the user's inbox, AgentMail gives agents their own dedicated inboxes — the agent gets a real email address (e.g., hermes-agent@agentmail.to) and can send, receive, and manage email autonomously.

Source: Google ADK AgentMail integration docs, AgentMail docs, agentmail-mcp repo.

This is not a replacement for our existing email solutions (himalaya for IMAP/SMTP, Google Workspace for Gmail API). Those let the agent operate the user's personal email. AgentMail is a new capability: agent identity and autonomous email communication. Use cases include agent-to-human outreach, agent-to-agent messaging, automated support workflows, email-based authentication, and service sign-ups.

Skill vs Tool vs Bundled?

Per CONTRIBUTING.md:

• Not a tool — No custom Python integration needed. Hermes's built-in native MCP support (tools/mcp_tool.py) already handles tool discovery, registration, API key passthrough, reconnection, and credential sanitization. Adding AgentMail is a config.yaml entry, not new code.
• A skill — The value-add is setup documentation, usage patterns, and workflow examples for the 11 MCP tools that auto-register once configured.
• Not bundled — Per CONTRIBUTING.md: "If your skill is specialized (a niche engineering tool, a specific SaaS integration, a game), it's better suited for a Skills Hub." AgentMail is a specific third-party SaaS integration, not broadly useful to all users. → Skills Hub candidate.

Research Findings

How AgentMail Works

AgentMail provides a REST API (base URL: https://api.agentmail.to/v0/) with Python and Node SDKs, plus an MCP server (npx -y agentmail-mcp).

Core concepts:

• Inboxes — Create/delete on-demand via API. Each inbox = a real email address. Default domain @agentmail.to, or custom domains on paid plans.
• Threads — Email conversations grouped automatically. Support labels, filtering by date.
• Messages — Send, reply, forward with text/HTML bodies and attachments.
• Webhooks — Real-time event notifications (message.received, message.sent, message.delivered, message.bounced, message.complained, message.rejected, domain.verified).
• WebSockets — Persistent bidirectional connection for real-time events (Python SDK has sync/async support).

MCP Server provides 11 tools (auto-registered by Hermes's native MCP support):

Authentication: Simple API key (prefix am_). No OAuth complexity.

Pricing (free tier available):

Key Design Decisions

1. API-first, not UI-first — No webmail interface; everything is programmatic. Perfect for agents.
2. Usage-based vs per-seat — Traditional providers charge ~$12/inbox/month; AgentMail bundles inboxes with volume pricing.
3. Idempotent creation — client_id parameter prevents duplicate inboxes/webhooks on re-runs.
4. MCP-native — First-class MCP server support means it slots directly into Hermes's native MCP infrastructure.

Current State in Hermes Agent

We have two existing email solutions, neither of which provides agent-owned identity:

Verified: Adding this to ~/.hermes/config.yaml auto-discovers and registers all 11 tools as first-class agent tools:

mcp_servers:
  agentmail:
    command: "npx"
    args: ["-y", "agentmail-mcp"]
    env:
      AGENTMAIL_API_KEY: "am_..."

No codebase changes needed at all.

Implementation Plan

What We'd Need

• AgentMail API key (user creates account at console.agentmail.to)
• Node.js for MCP server (npx -y agentmail-mcp)
• The mcp Python package installed (Hermes optional dependency)

Deliverable: Skills Hub Skill

Create an agentmail skill for the Skills Hub (not bundled) containing:

1. SKILL.md — Setup instructions (get API key, add MCP config), usage patterns for all 11 tools, workflow examples (create inbox → send email → check replies)
2. references/ — Quick reference for tool parameters, webhook event types, common patterns
3. Trigger conditions: "agent email", "agentmail", "agent inbox", "email identity"

Potential Future Enhancements (beyond the skill)

• Webhook listener — Reactive email processing (agent responds to incoming emails). Requires a public server or cronjob-based polling fallback.
• Agent identity persistence — Store the agent's email address in memory/config for cross-session use.
• Cross-platform delivery — Forward received emails to user's active platform (Telegram, Discord, CLI).
• Setup wizard integration — Add AgentMail as a config option during hermes setup (relates to Feature: Interactive tool selection during initial setup #322).

Pros & Cons

Pros

• Unique capability — Agent-owned email identity opens entirely new workflows that himalaya/Gmail can't provide.
• Zero codebase changes — Works through Hermes's native MCP support. Config + documentation only.
• Minimal setup — API key → config.yaml → done. No OAuth, no IMAP credentials.
• Native MCP fit — Auto-discovered tools, credential passthrough, reconnection — all handled by existing infrastructure.
• Free tier sufficient for personal use — 3 inboxes, 3K emails/month.
• SOC 2 certified — Enterprise-grade security.

Cons / Risks

• Third-party SaaS dependency — YC W25 startup. Vendor risk. No self-hosted option.
• Free tier limits — 100 emails/day, 3K/month. Power users pay $20+/mo.
• Webhook complexity — Real-time inbound processing requires a public server most CLI users won't have.
• Not a replacement — Additive to himalaya/Gmail, not a substitute for user's personal email.
• @agentmail.to domain — Free tier emails may look unfamiliar to recipients. Custom domains require paid plans.
• Node.js dependency — MCP server requires npx. Present on most dev machines but not universal.

Open Questions

1. Skills Hub readiness — Is the Skills Hub infrastructure ready for this to be published, or should we wait?
2. Security guardrails — Should agent email sending require user approval? Relates to Address outbound threats #129 (outbound threats).
3. Inbound email handling — Is cronjob-based polling sufficient, or should we invest in webhook support?
4. Priority — Is agent-owned email identity high-priority or nice-to-have?

References

• Google ADK AgentMail integration docs
• AgentMail website
• AgentMail documentation
• AgentMail MCP Server (GitHub)
• AgentMail Python SDK (GitHub)
• AgentMail Toolkit (GitHub)
• AgentMail pricing
• AgentMail webhook docs
• Hermes CONTRIBUTING.md — Skill vs Tool
• Hermes MCP implementation