Send & Receive Emails with Hermes

Hermes is Nous Research’s open source agent harness, which shares its name with Nous’s Hermes model family. This page covers the harness. It connects to AgentMail through its built-in MCP client, so your agent gets typed email tools it can call from chat, from subagents, and from scheduled jobs.

Once the two are wired together, Hermes creates its own @agentmail.to inbox, sends and answers email for you, and runs parallel subagents that each work from an inbox of their own.

0. Get the prerequisites

Install Hermes if you have not already. The installer runs a setup wizard where you pick a model provider. The details are in the Hermes installation guide.

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Generate an API key from the AgentMail Console and add it to ~/.hermes/.env. Every Hermes process loads that file, including unattended scheduled runs, so the key does not depend on the shell you start from:

export AGENTMAIL_API_KEY="<API_KEY>"
echo "AGENTMAIL_API_KEY=$AGENTMAIL_API_KEY" >> ~/.hermes/.env

Check that the key works before wiring it into Hermes:

npm install -g agentmail-cli
agentmail inboxes list

An empty list is fine. You have not created an inbox yet.

1. Register the AgentMail tools

Add the hosted AgentMail MCP server to ~/.hermes/config.yaml:

mcp_servers:
  agentmail:
    url: "https://mcp.agentmail.to/mcp"
    headers:
      x-api-key: "${AGENTMAIL_API_KEY}"

Hermes resolves ${AGENTMAIL_API_KEY} when it connects, reading your environment and ~/.hermes/.env. The key itself stays out of the config file.

Check the connection:

hermes mcp test agentmail
hermes mcp list

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:

  MCP Servers:

  Name             Transport                      Tools        Status
  ──────────────── ────────────────────────────── ──────────── ──────────
  agentmail        https://mcp.agentmail.to/mcp   all          ✓ enabled

Every tool registers under a prefixed name such as mcp__agentmail__create_inbox, so it cannot collide with a built-in tool or another server’s tools. You will not call these names yourself. Prompt in plain language and Hermes picks the tool.

If Hermes is already running, type /reload-mcp in the chat to pick up config changes without a restart.

To expose only the operations your agent needs, add a tools filter to the server entry. Only the listed tools register. An exclude list works the same way in reverse, and both accept globs:

mcp_servers:
  agentmail:
    url: "https://mcp.agentmail.to/mcp"
    headers:
      x-api-key: "${AGENTMAIL_API_KEY}"
    tools:
      include: [create_inbox, send_message, list_threads, get_thread, reply_to_message]

The full tool catalog, OAuth and API key details, and the local stdio bridge are on MCP and Skills.

2. Test sending an email

Start hermes and ask it to create an inbox and email you. Put your everyday address in place of you@example.com:

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".

The message reaches that account within moments. Hermes makes two tool calls: create_inbox returns the new address, and send_message sends from it. The send returns the message’s message_id and the thread_id of the conversation it starts, which Hermes uses to keep any follow-up in the same thread.

Asking for an inbox without naming a username always works, because AgentMail generates the address.

You can confirm the send from outside Hermes with the CLI. Use the address Hermes reported:

agentmail inboxes:messages list --inbox-id "support-agent@agentmail.to"

The email you just sent is at the top, carrying the sent label.

3. Test receiving and replying

Reply to the email from your own account, then ask Hermes to handle it:

Check the support-agent inbox for new mail and reply to the latest message
with a short acknowledgment.

Hermes lists the inbox’s threads, reads the new message, and calls reply_to_message. The reply arrives in the same thread of your mailbox. A message takes about two seconds to deliver in either direction. If Hermes reports nothing new, ask it to check again.

The reading tools return mail written by external senders, and their descriptions tell the model not to treat that content as instructions. Agent safety covers the rest of the inbound picture.

4. Give every subagent its own inbox

Hermes spreads work across parallel subagents with its delegate_task tool. Each subagent runs an isolated conversation in its own terminal session and inherits the parent’s toolsets, including the AgentMail tools. So each one 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.

Try a three-way fanout. Put a real signup target in place of <service>:

Delegate to three parallel subagents. Each one should create its own AgentMail
inbox, sign up for <service> with that address, wait for the verification
email, extract the code, complete the signup, report back, and delete its inbox.

Each subagent sends only its final summary back to the parent, so the parent’s context stays small while the inbox work runs in parallel. Hermes runs up to three subagents at once by default. A larger batch returns a tool error instead of queueing, so raise delegation.max_concurrent_children in config.yaml before asking for a wider fanout. When you narrow a subagent’s toolsets, the parent’s MCP toolsets are kept by default. Set inherit_mcp_toolsets: false for a strict intersection.

This pattern fits signup verification, parallel outreach threads, and QA runs that each need a clean email identity.

5. Schedule a recurring inbox check

Hermes has a built-in scheduler you drive in plain language, and scheduled runs load the same MCP servers as your chat sessions, reading the key from ~/.hermes/.env. Ask for the job:

Every weekday at 9am, check the support-agent inbox for unread mail, summarize
anything new, and draft replies for the urgent messages.

Jobs fire through the Hermes gateway, so install it as a service with hermes gateway install if the schedule should run with no chat open.

Next Steps