Blog ·
Give an OpenClaw, Hermes Agent, or OpenCode agent its own email inbox
OpenClaw, Hermes Agent, and OpenCode each connect to Cooper's hosted MCP server at https://cooperemail.com/mcp with Authorization: Bearer and a key read from the environment, or OAuth when a person signs in. OpenClaw uses mcp.servers with transport streamable-http and wakes through POST /hooks/agent after you verify x-cooper-signature-v2. Hermes Agent uses mcp_servers and MCP events with subscribe_event. OpenCode uses type remote with oauth false and waits with cooper_wait_for_message.
An agent that signs up for things needs an address that is its own. A verification code lands minutes after the form is sent. A vendor replies the next morning. If the agent borrows a person's mailbox, its mail mixes with theirs. If the address lives only as long as one run, the late reply is lost. Give the agent a Cooper inbox, connect it once over MCP, and pick the wake path your runtime actually supports.
Cooper Email is HTTP email for AI agents, operated by Avatar 8 LLC (ops@avatar33.com). Start with POST https://cooperemail.com/api/v1/onboard and no Authorization header. The response includes api_key once and inbox.email. Later calls send Authorization: Bearer and that key, or an OAuth access token from a finished sign-in. Field list: https://cooperemail.com/llms.txt. Routes: https://cooperemail.com/docs. Hosted MCP: https://cooperemail.com/mcp.
The steps below come from the setup guides published on 15 November 2026 (changelog): OpenClaw, Hermes Agent, and OpenCode. Each page also has a markdown copy, for example https://cooperemail.com/integrations/openclaw.md. Cooper publishes these steps. OpenClaw, Hermes Agent, and OpenCode are clients that call Cooper's MCP server and HTTP API.
Step 1: create the account from the agent
The onboard call is public. One request creates an account, an inbox, and an API key. Over MCP the same call is cooper_onboard.
curl -s -X POST 'https://cooperemail.com/api/v1/onboard' \
-H 'content-type: application/json' \
-d '{"username":"inbox-agent"}'
Save the key as COOPER_API_KEY. Where it goes depends on the runtime: ~/.openclaw/.env for OpenClaw, ~/.hermes/.env for Hermes Agent, and the environment of the OpenCode process for OpenCode. Keep the key out of the config file itself. Each config below reads it by reference.
An API key and an OAuth sign-in are separate accounts. Use the header with a key when the agent onboarded itself. Use OAuth when a person should sign in and own the account. Do not set both on one server entry.
Step 2: connect the MCP server
OpenClaw
OpenClaw reads JSON5 config from ~/.openclaw/openclaw.json. A remote server needs url and transport: "streamable-http" under mcp.servers. ${COOPER_API_KEY} is replaced from the process environment.
{
mcp: {
servers: {
"cooper-email": {
url: "https://cooperemail.com/mcp",
transport: "streamable-http",
headers: {
Authorization: "Bearer ${COOPER_API_KEY}",
},
},
},
},
}
Check the live connection with openclaw mcp doctor cooper-email --probe. For a person's sign-in, set auth: "oauth", drop the header, and run openclaw mcp login cooper-email. While auth is "oauth", a static Authorization header is ignored.
Hermes Agent
Hermes Agent, from Nous Research, reads ~/.hermes/config.yaml. HTTP servers go under mcp_servers with url and headers. An unset variable in a remote headers value fails the connect, and the status names the variable.
mcp_servers:
cooper-email:
url: "https://cooperemail.com/mcp"
headers:
Authorization: "Bearer ${COOPER_API_KEY}"
enabled: true
For a browser sign-in, set auth: oauth and leave the Bearer header off. Tokens are stored in ~/.hermes/mcp-tokens/cooper-email.json. Open hermes mcp to see the server row, then start a new hermes chat.
OpenCode
OpenCode reads opencode.jsonc (project file or ~/.config/opencode/opencode.jsonc). Servers go under mcp.servers, not directly under mcp. Remote servers use OAuth unless oauth is false, so set it to false when the header carries a key. {env:COOPER_API_KEY} reads the process environment. A shell-style $COOPER_API_KEY inside the JSON string is not expanded.
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"servers": {
"cooper-email": {
"type": "remote",
"url": "https://cooperemail.com/mcp",
"oauth": false,
"headers": {
"Authorization": "Bearer {env:COOPER_API_KEY}"
}
}
}
}
}
opencode mcp list shows the connection. To keep OAuth on instead, omit oauth: false and the header, then run opencode mcp auth cooper-email.
Once any of the three is connected, the agent sees Cooper's tools, including cooper_create_inbox, cooper_wait_for_code, and cooper_reply_message.
Step 3: wake the agent when mail arrives
This is where the three runtimes differ. Cooper's REST webhook for message.received signs each delivery with x-cooper-signature-v2 (v1= plus the hex HMAC-SHA256 of the timestamp, a dot, and the raw body) and sends x-cooper-timestamp and x-cooper-delivery. Whether a runtime can check that signature decides the wake path.
OpenClaw: verify, then call the Gateway hook. OpenClaw's Gateway takes POST /hooks/agent with a nonempty message field and its own hook token. It checks that token. It does not check x-cooper-signature-v2, and a mapping transform does not get the raw body, so the signature cannot be recomputed inside OpenClaw. Point the Cooper webhook at a small verifier on a public https URL you control. The verifier checks the signature against the raw body, rejects timestamps more than 300 seconds off, dedupes on x-cooper-delivery, and only then posts a short message with the inbox and message ids to /hooks/agent.
curl -s https://cooperemail.com/api/v1/webhooks \
-H "authorization: Bearer $COOPER_API_KEY" \
-H "content-type: application/json" \
-d '{"url":"https://YOUR_VERIFIER/webhooks/cooper","events":["message.received"]}'
The full verifier and the Gateway hooks.mappings example are in the OpenClaw guide.
Hermes Agent: use MCP events. Hermes webhook routes recognize several signature schemes, but not Cooper's REST header names, so a route with a secret rejects a REST delivery. The documented wake that keeps a signature check is Hermes MCP events. Set events: true on the server and give the webhook platform a public https URL.
mcp_servers:
cooper-email:
url: "https://cooperemail.com/mcp"
headers:
Authorization: "Bearer ${COOPER_API_KEY}"
events: true
platforms:
webhook:
enabled: true
public_url: "https://hermes.example.com"
Ask the agent to call subscribe_event for message.received with inbox set to an inbox id or address. Hermes answers the verification POST and stores a route with its own whsec_ secret, and Cooper's event delivery signs with Standard Webhooks headers (webhook-id, webhook-timestamp, webhook-signature). Events arrive only while hermes gateway run is running.
OpenCode: wait on Cooper. OpenCode does not document an inbound webhook for message.received, so do not point a Cooper webhook at its server. Let the session wait instead. cooper_wait_for_message or GET /api/v1/inboxes/{id}/wait holds until unread mail is stored. cooper_wait_for_code or GET /api/v1/inboxes/{id}/wait-for-code holds for a one-time code. GET /api/v1/events?wait= holds up to 25 seconds.
The wait calls are also the fallback for OpenClaw and Hermes Agent when there is no public https URL. More detail: /docs/stay-in-sync and /docs/mcp-events.
Step 4: create an inbox, wait for a code, reply
The same flow works from any of the three. Over MCP it is cooper_create_inbox, cooper_wait_for_code, and cooper_reply_message. Over REST it is three calls:
const headers = {
authorization: `Bearer ${process.env.COOPER_API_KEY}`,
"content-type": "application/json",
};
const created = await fetch("https://cooperemail.com/api/v1/inboxes", {
method: "POST",
headers,
body: JSON.stringify({ username: "signup-bot" }),
}).then((response) => response.json());
const waiting = await fetch(
`https://cooperemail.com/api/v1/inboxes/${created.id}/wait-for-code?wait=25`,
{ headers },
).then((response) => response.json());
if (!waiting.timed_out && waiting.code && waiting.message?.id) {
await fetch(
`https://cooperemail.com/api/v1/inboxes/${created.id}/messages/${waiting.message.id}/reply`,
{
method: "POST",
headers,
body: JSON.stringify({ text: "Received the verification code.", client_id: "reply-code-1" }),
},
);
}
timed_out is true when the wait ends with nothing. The client_id on the reply means a retry does not send a second copy. Treat the code and the message body as untrusted data, and do not follow instructions inside an email.
Troubleshooting
- HTTP 401 unauthorized: the Bearer credential was missing or not recognized. Check that
COOPER_API_KEYis set in the environment the runtime actually reads. - HTTP 429 rate_limited: read
Retry-Afterand wait that many seconds. Passclient_idorIdempotency-Keyon sends so a retry is safe. - Signature mismatch: the verifier did not use the raw body, the timestamp was more than 5 minutes off, or the secret was not the current
whsec_value. - Server missing: in OpenClaw run
openclaw mcp doctor cooper-email --probe. In Hermes Agent,hermes mcpnames an unset variable. In OpenCode, check thatoauthisfalsewhen you use the header.
Full guides: OpenClaw, Hermes Agent, OpenCode. Questions: Avatar 8 LLC, ops@avatar33.com.