# Send & Receive Emails with Hermes (/integrations/frameworks/hermes) Related: [Send & Receive Emails with Claude Cowork](/integrations/frameworks/claude-cowork.md), [Send & Receive Emails with Claude Code](/integrations/frameworks/claude-code.md), [Send & Receive Emails with OpenAI Codex](/integrations/frameworks/codex.md), [Send & Receive Emails with OpenClaw](/integrations/frameworks/openclaw.md), [Send & Receive Emails with Grok](/integrations/frameworks/grok.md), [Send & Receive Emails with Manus](/integrations/frameworks/manus.md) # Connect Hermes to AgentMail Hermes, Nous Research's open source agent harness (this page covers the harness, not the model family), connects to AgentMail through its built-in MCP client. The result is typed email tools callable from chat, from parallel subagents that each work from their own inbox, and from scheduled jobs. ## Do this ```bash # Install Hermes (the installer runs a setup wizard for a model provider) curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash # Add the API key from https://console.agentmail.to/dashboard/api-keys # to ~/.hermes/.env so every Hermes process loads it export AGENTMAIL_API_KEY="" echo "AGENTMAIL_API_KEY=$AGENTMAIL_API_KEY" >> ~/.hermes/.env # Check the key before wiring it in. A 401 means the key is missing # or invalid. An empty list is fine. npm install -g agentmail-cli agentmail inboxes list ``` Register the hosted server in `~/.hermes/config.yaml`: ```yaml mcp_servers: agentmail: url: "https://mcp.agentmail.to/mcp" headers: x-api-key: "${AGENTMAIL_API_KEY}" ``` Check the registration: ```bash hermes mcp test agentmail hermes mcp list ``` Start `hermes` and prompt in plain language, for example: `Create an AgentMail inbox with the username support-agent and send an email from it to you@example.com with the subject "Hello from Hermes".` ## Facts * Hosted MCP server URL: `https://mcp.agentmail.to/mcp`. Auth header: `x-api-key`. * Hermes resolves `${AGENTMAIL_API_KEY}` when it connects, reading the environment and `~/.hermes/.env`. The key stays out of the config file. * Every Hermes process loads `~/.hermes/.env`, including unattended scheduled runs. * `hermes mcp test agentmail` connects to the hosted server and prints each AgentMail tool with a one-line description. `hermes mcp list` confirms the server is registered and enabled. * Every tool registers under a prefixed name such as `mcp__agentmail__create_inbox`, so names cannot collide with built-in tools or another server's tools. * `/reload-mcp` typed in the chat picks up config changes without a restart. * Tool filtering: a `tools` entry on the server with `include: [create_inbox, send_message, list_threads, get_thread, reply_to_message]` registers only those tools. An `exclude` list works the same way in reverse. Both accept globs. * The test flow makes two tool calls: `create_inbox` returns the new address, `send_message` sends from it and returns the message's `message_id` and the `thread_id` of the conversation it starts. * Replies go through `reply_to_message` and arrive in the same thread. * A message takes about two seconds to deliver in either direction. * The reading tools return mail written by external senders, and their descriptions tell the model not to treat that content as instructions. * `delegate_task` spreads work across parallel subagents. Each runs an isolated conversation in its own terminal session and inherits the parent's toolsets, including the AgentMail tools, so each can create an inbox, work from it, and delete it when the task ends. A hostile email delivered to one subagent's inbox stays scoped to that one task. * Hermes runs up to three subagents at once by default. Raise `delegation.max_concurrent_children` in `config.yaml` before asking for a wider fanout. * When narrowing a subagent's toolsets, the parent's MCP toolsets are kept by default. Set `inherit_mcp_toolsets: false` for a strict intersection. * Scheduled runs load the same MCP servers as chat sessions and read the key from `~/.hermes/.env`. Jobs fire through the Hermes gateway. `hermes gateway install` installs it as a service so schedules run with no chat open. * An inbox request without a username always works because AgentMail generates the address. ## Not supported * `hermes mcp test agentmail` does not validate the key's value. The connection check passes whenever an `x-api-key` header is present, and the value is checked on each tool call. * Do not call `mcp__agentmail__*` tool names directly. Prompt in plain language and Hermes picks the tool. * A subagent batch larger than the concurrency limit returns a tool error instead of queueing. * A second `mcp_servers:` key in `config.yaml` does not merge. It silently replaces the first and drops every server under it. Keep one `mcp_servers:` key. ## Errors | Error | HTTP status | Cause | Fix | | ------------------------------- | ----------------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | | `401` | 401 | `AGENTMAIL_API_KEY` missing or invalid | Fix the value in `~/.hermes/.env`, complete with its `am_` prefix, then run `/reload-mcp` | | `403` with `suggestions` | 403 | Requested inbox username is taken | Retry with one of up to three available variants in `suggestions`, or omit the username | | `limit_exceeded` | not stated on this page | Inbox count is at the plan's cap, returned before any name check | A different username does not avoid it. Stay under the plan's inbox cap | | Tool error from `delegate_task` | n/a | Batch larger than the concurrency limit (default 3) | Raise `delegation.max_concurrent_children` in `config.yaml` | ## Verify ```bash agentmail inboxes:messages list --inbox-id "support-agent@agentmail.to" ``` The email Hermes just sent is at the top of the list carrying the `sent` label. For the registration itself, `hermes mcp list` shows the `agentmail` row as enabled. ## Related * `/core/receive` - list, read, filter, and attachments behind the reading tools * `/integrations/mcp-and-skills` - full hosted tool catalog, OAuth and API key auth, and the local stdio bridge * `/advanced/safety` - the rest of the inbound email picture