Docs

Waking your agent when mail arrives

The three ways an agent finds out mail landed, and which one belongs to which kind of agent.

An agent learns that mail arrived in one of three ways, and choosing correctly between them is most of the work. Two of them need nothing built.

The assistant looks when it needs to
Nothing to set up. An assistant with the tools connected calls list_messages when the conversation calls for it. This is the right answer whenever a person is sitting in front of it.
It waits for one reply
wait_for_reply blocks until an answer lands in a thread, up to five minutes at a time. The right answer when an agent has just sent something and cannot continue without the response.
You are told
A webhook: we POST to an address you give us the moment mail arrives. The only option that costs nothing while nothing is happening, and the only one that still works when the agent is not currently running.

What every receiver needs first

We only POST to public https. A runtime on your own machine is not reachable, and a private address is refused when you register it, so put a tunnel in front of it: mcpmailer tunnel --handle scout --target http://localhost:PORT gives you https://scout.mcpmailerwire.com pointing at that port, and that hostname survives restarts and network changes.

Then register the endpoint, in the dashboard under Webhooks, with create_webhook, or with mcpmailer webhooks:add, asking for the events you want: a new endpoint is subscribed to message.received and nothing else.

Where the setup for yours lives

OpenClaw Its hook routes, /hooks/wake and /hooks/agent, with the body template for each.Hermes Its webhook adapter: the route, the secret, and the prompt template our payload fits.Your own service Take the envelope, verify the signature, ignore an id you have already handled.n8n A Webhook node with Header Auth, feeding the AI Agent node.

OpenClaw and Hermes get pages of their own because they are the two here meant to run unattended, and an agent that answers mail at three in the morning has more to get right than a connection string.

A desktop assistant like Claude

This one cannot be woken, and it is worth saying plainly rather than leaving you to find out. A chat app has no inbound address for us to POST to: Claude, ChatGPT, and the like read mail when you ask them to, or wait inside a single task with wait_for_reply. If mail has to be handled while nobody is looking, the thing handling it has to be something that runs unattended.