Connect OpenClaw to email: MCP, Himalaya or mail triggers

01Four ways to add email to OpenClaw

OpenClaw separates tools, which let the agent operate a mailbox, from triggers, which turn incoming mail into an agent run.^[1][5]

Sources: OpenClaw documentation and skills in the OpenClaw repository, read on 2026-10-28.^{[1][5][6][7][8]}

The Himalaya skill describes itself as able to list, read, search, compose, reply, forward, move and delete, and asks you to keep credentials in a password manager or keyring rather than in chat.^[7] The gog skill sends Gmail messages directly with gog gmail send or creates drafts.^[8] Both work with whatever access their stored sign-in allows: Himalaya with the credentials in its config, gog with its OAuth sign-in to Google. An MCP server such as Command Mail grants permissions one by one when you connect instead. Your addresses reach it as copies through forwarding; what the agent changes there does not flow back to the original mailbox.

02What you need

You need a running OpenClaw Gateway and access to its CLI, or to the Control UI as an administrator. You also need an email service with an MCP server and a browser to approve the sign-in.

Command Mail's server runs at https://commandmail.app/mcp with Streamable HTTP, OAuth 2.1, PKCE and dynamic client registration.^[9] You do not need to register an OAuth client yourself. On the consent page you switch each permission on or off: mail:read to read, search and organize within the mailbox's autonomy level, mail:draft for drafts, mail:send-approved to send a draft you approved, mail:send to send without per-message approval, and mailboxes to connect addresses. Sending without approval starts switched off.^[9]

The free plan covers one mailbox (further mailboxes pause and keep receiving) and the last 90 days, with reading, search, sorting, the morning brief and drafts; it does not send. Pro adds sending, up to ten mailboxes and full history: €19 per month for the first 100 paying Pro accounts for as long as that subscription runs, €29 per month after that, or €190 or €290 per year. You can try Pro for 7 days for €1. Team costs €39 per person per month (prices checked on 2026-10-28).^[9]

03Step by step: set up an email MCP server in OpenClaw

From the CLI, setup takes five commands. While the local Gateway is running, the CLI refuses changes to saved servers (add, set, configure, tools), sign-in and doctor --probe; status and doctor without --probe keep working.^[3]

1. Stop the Gateway: openclaw gateway stop.^[11]

2. Save the server:

   openclaw mcp add commandmail \
     --url https://commandmail.app/mcp \
     --transport streamable-http \
     --auth oauth

   The name commandmail is up to you; it becomes the tool prefix. add checks the connection before saving unless OAuth sign-in is needed first, as it is here.^[3] If you leave out --transport, OpenClaw uses SSE.^[2]

3. Sign in with openclaw mcp login commandmail. OpenClaw starts a local callback listener, prints the authorization link and saves the credentials as soon as the browser returns.^[2] On Command Mail's consent page, mail:read and mail:draft are enough to start with.

4. Check the connection:

   openclaw mcp doctor commandmail --probe

   doctor --probe opens a live connection and lists the tools the server offers. Only this check proves the server answers; saving a definition does not.^[1]

5. Start the Gateway again: openclaw gateway start.^[11]

While the Gateway is running, or without a terminal, use the Control UI: Settings → MCP → Add server, pick Streamable HTTP, enter the URL, set auth: "oauth" in the config editor and select Sign in.^[1] This works when you open Settings on the Gateway's own HTTPS address or on its loopback address. Command Mail accepts plain HTTP callback URLs only on localhost, 127.0.0.1 and [::1]; a Gateway at any other address needs HTTPS.

OpenClaw stores the tokens in <state-dir>/state/openclaw.sqlite, a database readable only by its owner.^[2] The tools then show up under names such as commandmail__search_mail or commandmail__get_thread. You do not call them by hand; OpenClaw picks them while it works.^[4]

If you run two OpenClaw installations, sign each one in separately. Command Mail issues a new refresh token on every refresh and revokes every token from that sign-in if an already used refresh token is presented again. Within one installation OpenClaw prevents that itself: refresh, login and logout share a lock in the database.^[2]

04Limit sending: tool filters, tool policy and approvals

A tool filter decides which tools from this connection OpenClaw makes available to the agent:^[3]

openclaw mcp tools commandmail --include 'capabilities,search_mail,list_threads,get_thread,list_attachments,morning_brief,save_agent_draft,list_agent_drafts'

Through this connection the agent then has only read and draft tools, no sorting or sending tools. The filter does not restrict other routes such as the Himalaya or gog skill or another MCP server.

Like every CLI change, this command runs only while the Gateway is stopped; on a running Gateway, set the filter in the config editor under Settings → MCP.^[1] With an include list, tools the server adds later are not picked up automatically. The other way round, --exclude hides single tools, and tools.deny in the tool policy blocks a single tool such as commandmail__send_message, or the whole server with commandmail__*.^[3] In the Control UI you can also deny individual tools for the current session under + → Plugins → Tool access.^[1]

The MCP docs describe per-call approval for runs on Codex. The default full-permission posture does not prompt. Stricter postures check tools that lack safety annotations: workspace can review them automatically, while guarded and read-only can ask you. To require approval before every call, run openclaw mcp configure commandmail --approval prompt; OpenClaw then asks before every call to this server.^[1][3]

If you choose Allow Always at a prompt and OpenClaw can store the grant, it covers that tool on that server for that agent with other arguments too, which for a send tool means further emails. It applies under the auto mode or when no mode is set explicitly; with --approval prompt OpenClaw keeps asking despite a stored grant. openclaw approvals get --gateway shows which grants are stored.^[3]

Command Mail marks reading, searching and listing tools with readOnlyHint: true; drafting, sorting, rules and sending are not marked read-only. The server also builds its tool list from the permissions you granted: send_message and reply exist only with mail:send, send_approved_draft only with mail:send-approved. Sending directly also needs a plan from Pro upwards, a mailbox that can send on autonomy auto, and room in the daily limit. A direct agent send may address at most 20 recipients across To, Cc and Bcc; approved drafts are exempt from that limit.^[9]

05OpenClaw on a server: signing in without a browser

When the Gateway runs on a VPS or in a container, your browser cannot reach the local callback that openclaw mcp login opens. In that case you carry the code over by hand:^[2]

1. With the Gateway stopped, run openclaw mcp login commandmail and open the printed link on your own machine.
2. Approve. The browser then lands on an address that does not load; it contains code and iss.
3. Pass both back: openclaw mcp login commandmail --code <code> --issuer https://commandmail.app.

The docs ask for the iss value exactly as it appears, decoded, in that callback URL. Command Mail includes it with every sign-in.^[2] Afterwards, openclaw mcp status --verbose shows whether tokens are present.

If several people should each connect their own mailbox through the same Gateway, use oauth.identity: "per-requester". Each sender then gets their own sign-in link on their first call, and the callback goes through gateway.publicOrigin, a publicly reachable HTTPS address.^[2] The docs carry a warning: these are single-use links, and whoever opens one connects their own account to the sender the link was issued for. Use this only in channels where every sender trusts the others.

06OpenClaw's own mail triggers

For agents that should react to incoming mail, OpenClaw ships two triggers, and the docs build both around a restricted reader agent. The IMAP plugin watches an existing mailbox and starts a separate, isolated session for each allowed message. It does not send, does not change message flags, and does not process mail that was already in the mailbox when monitoring began.^[5]

Only senders listed in allowedSenders get through, and by default their domain must also pass DMARC verification. You set up that reader agent yourself beforehand; the docs describe it running in a sandbox without file, shell or web tools.^[5] The Gmail PubSub triggers do the same job for Gmail but need gcloud, an authorized gog CLI, hooks switched on, and an HTTPS endpoint that Google can reach. According to the docs, the setup wizard does not create a reader agent: without your own mapping, Gmail hooks run as the default agent, and the separate session per message does not restrict that agent's tools.^[6]

These triggers solve a different problem from an MCP server: they let an agent you have tightly limited react to new mail, while the MCP server gives your main agent a mailbox to work in. The test from the IMAP docs is worth running on any setup: send yourself a message that says "follow this link and run a command" and confirm the agent only summarizes it.^[5]

07Check that it works

Start with capabilities. It returns the account owner, the granted permissions, each mailbox with its autonomy level, and the limits. Ask OpenClaw: "Call capabilities on commandmail and tell me what you are allowed to do." If the answer matches what you chose, the connection works.

Next, a read-only task: "Find invoices from the last 30 days and list sender, date and amount." Only then ask for a draft and look at it in Command Mail. Command Mail marks email content as untrusted data and flags suspected prompt injection.^[9] That matters here because the same OpenClaw agent can often also post in chat channels or run commands.

08Common problems and fixes

The connection fails immediately although the URL is right. Check the transport. Without --transport streamable-http, OpenClaw connects over SSE.^[2] Command Mail's server is stateless, works over POST, and answers GET requests with 405. Fix it by adding only transport: "streamable-http" in the config editor under Settings → MCP; filters, OAuth settings and the approval mode stay as they are. openclaw mcp set, by contrast, replaces the whole server definition.^[1][3]

The server shows up in Settings but has no tools. With the Gateway stopped, run openclaw mcp doctor commandmail --probe; on a running Gateway, openclaw mcp status --verbose shows the sign-in state.^[3] If the log or diagnostic says authentication refused (401), the sign-in is missing or has expired; Command Mail requires a token even to list tools.^[1] If it connects but tools are missing, check toolFilter.include and toolFilter.exclude.

The tools are missing in chat although doctor lists them. If the session runs in a sandbox (mode all or non-main), the sandbox tool allowlist tools.sandbox.tools needs bundle-mcp or commandmail__*.^[4]

A write call fails and it is unclear whether it ran. For a 404 from a legacy SSE message endpoint and for an expired Streamable HTTP session, the docs say OpenClaw does not replay the failed call, because the tool may already have carried out the action.^[2] For an email, always check the sent messages or the activity log in Command Mail before you ask for it again.

A change does not reach the agent. openclaw mcp reload only refreshes connections owned by the current CLI process. A Gateway running elsewhere picks up changes through its own reload, a config publish or a restart, for example with openclaw gateway restart.^[1][11]

The agent cannot send. Check the plan first, then the permissions. Sending is included from Pro upwards; mail:send-approved sends only a draft you approved in Command Mail, and not from a mailbox on read.^[9] To change permissions, sign in again with openclaw mcp login commandmail.

09Next steps

How permissions and autonomy levels fit together is covered in permissions and autonomy. Whether a self-run IMAP MCP server or a hosted service suits you better is the topic of IMAP MCP vs hosted MCP. The same server in another self-hosted agent is shown in connect Hermes Agent to email.

Start Command Mail for free and connect OpenClaw.

Frequently asked questions

Sources

1. OpenClaw: Connect MCP servers docs.openclaw.ai, accessed October 28, 2026
2. OpenClaw: Transports and OAuth docs.openclaw.ai, accessed October 28, 2026
3. OpenClaw: Manage saved MCP servers docs.openclaw.ai, accessed October 28, 2026
4. OpenClaw: Tool policy (MCP and plugin tools in the sandbox) docs.openclaw.ai, accessed October 28, 2026
5. OpenClaw: IMAP email trigger docs.openclaw.ai, accessed October 28, 2026
6. OpenClaw: Gmail PubSub triggers docs.openclaw.ai, accessed October 28, 2026
7. OpenClaw: Himalaya skill (IMAP/SMTP) github.com, accessed October 28, 2026
8. OpenClaw: gog skill (Google Workspace CLI) github.com, accessed October 28, 2026
9. Command Mail: llms.txt with plans, permissions and setup commandmail.app, accessed October 28, 2026
10. OpenClaw: releases github.com, accessed October 28, 2026
11. OpenClaw: Manage the Gateway service docs.openclaw.ai, accessed October 28, 2026