# Hermes and MCPmailer

Hermes agents use MCPmailer as a standard MCP tool server for sending and receiving email.

Point Hermes at the MCPmailer endpoint and its agents can hold real email conversations, with your oversight rules applied on every send.

## Setup

1. **Create a mailbox** One per agent, so its address and its key are the same identity.
1. **Add the server** One entry under mcp_servers, with our endpoint as the url.
1. **Sign in once** With auth: oauth, Hermes runs the PKCE flow and keeps the token itself.
1. **Restart the agent** The tool list is read when the server connects.

## MCP server config

```
mcp_servers:
  mcpmailer:
    url: https://connect.mcpmailer.com/mcp
    auth: oauth
    timeout: 320
    connect_timeout: 30
```

## A bearer key instead of OAuth

Where you would rather hold a key than sign in, headers take one directly. Everything else about the entry stays the same.

```
mcp_servers:
  mcpmailer:
    url: https://connect.mcpmailer.com/mcp
    headers:
      Authorization: "Bearer mmk_live_..."
    timeout: 320
    connect_timeout: 30
```

## Worth knowing

### OAuth tokens survive a restart

With auth: oauth the token is cached at ~/.hermes/mcp-tokens/mcpmailer.json and refreshed automatically, so a rebuild does not send you back through the browser.

### Raise timeout above the wait

wait_for_reply can block for 300 seconds, so timeout has to clear that. connect_timeout is separate and can stay small.

### Or let mail start the run

Hermes has a webhook adapter of its own, so an agent does not have to be waiting on a tool call to hear about mail. Add a route under platforms.webhook and point a webhook at it: our payload already uses the dot paths its prompt templates expect, so {data.from} and {data.subject} resolve with no body template. We sign deliveries under the generic header names its recommended mode verifies, so the route needs the signing secret and nothing else. /docs/hermes has the route, tool filtering, cron, and running the gateway as a service.

### Send limits apply per mailbox

Cold sends draw down a daily and a monthly allowance; replies to people who wrote first are not throttled. get_mailbox_info returns what is left.


Docs: https://mcpmailer.com/docs.md