# Connect OpenClaw to email: MCP, Himalaya or mail triggers

> Connect OpenClaw to email: an OAuth MCP server with openclaw mcp add and login, tool filters, approvals, and the Himalaya, gog and IMAP trigger routes.

Updated: 2026-10-28 · Fact-checked: 2026-10-28 · Canonical: https://commandmail.app/en/guides/connect-openclaw-to-email · Deutsch: https://commandmail.app/de/anleitungen/openclaw-mit-e-mail-verbinden.md

One way to let OpenClaw work in the email addresses you already use is a remote MCP server: `openclaw mcp add` with the server URL, the `streamable-http` transport and `--auth oauth`, followed by `openclaw mcp login`.[^1][^3] OpenClaw also ships its own email routes: the Himalaya skill for a mailbox over IMAP/SMTP, the gog skill for Gmail, and two triggers that start an agent run when new mail arrives, which the docs recommend pointing at a specially restricted reader agent.[^5][^6][^7][^8] Which one fits depends on whether the agent should work in your addresses, run a mailbox of its own, or only react to incoming mail.

Command Mail is our product, so the examples use it as the MCP server. The steps work the same way for other email MCP servers that use Streamable HTTP and OAuth. We read the OpenClaw documentation on 2026-10-28; the latest stable release that day was v2026.10.8.[^10]

## Four 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]

| Route | What it is for | Sign-in | How the agent uses it |
|---|---|---|---|
| Email MCP server | read, sort, draft and send in existing addresses | OAuth via `openclaw mcp login` or Settings, or headers | tools prefixed `<server>__` |
| Himalaya skill | one mailbox over IMAP/SMTP from the shell | credentials in the Himalaya config | commands such as `himalaya message reply` |
| gog skill | Gmail, Calendar, Drive and other Google services | OAuth setup in gog | commands such as `gog gmail search` |
| IMAP trigger, Gmail PubSub | new mail starts an agent run; you set up the restricted reader agent yourself | IMAP password as a secret, or gcloud, gog and an HTTPS endpoint | an event, not a tool |

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.

## What 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]

## Step 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:

   ```bash
   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:

   ```bash
   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]

## Limit sending: tool filters, tool policy and approvals

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

```bash
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]

## OpenClaw 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.

## OpenClaw'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]

## Check 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.

## Common 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`.

## Next steps

How permissions and autonomy levels fit together is covered in [permissions and autonomy](https://commandmail.app/en/docs/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](https://commandmail.app/en/learn/imap-mcp-vs-hosted-mcp). The same server in another self-hosted agent is shown in [connect Hermes Agent to email](https://commandmail.app/en/guides/connect-hermes-agent-to-email).

[Start Command Mail for free](https://commandmail.app/login?signup=1) and connect OpenClaw.

## Frequently asked questions

### How do I add an email MCP server to OpenClaw?

Stop the Gateway with openclaw gateway stop, save the server with openclaw mcp add <name> --url <server-url> --transport streamable-http --auth oauth, run openclaw mcp login <name> and approve in the browser, check it with openclaw mcp doctor <name> --probe, and start the Gateway again with openclaw gateway start. While the Gateway is running, add the server in the Control UI under Settings → MCP instead.

### Can OpenClaw send email?

Yes: through an email MCP tool, through the bundled Himalaya skill over SMTP, or through the gog skill for Gmail. The IMAP trigger plugin does not send. With Command Mail, sending is included from Pro upwards; sending without per-message approval also needs the mail:send permission and a mailbox on autonomy auto.

### Does OpenClaw ask before it sends an email?

The MCP docs describe approvals for runs on Codex: the default full-permission posture does not prompt, stricter postures can review automatically or ask, and with openclaw mcp configure <name> --approval prompt OpenClaw asks before every call to that server. You can also limit sending with tool filters, tools.deny and the permissions you grant at the email service.

### How do I sign in when OpenClaw runs on a server without a browser?

openclaw mcp login prints an authorization link. Open it on your own machine, approve, and pass the code from the callback URL with openclaw mcp login <name> --code <code>. If the URL also contains iss, add it with --issuer; for Command Mail that is https://commandmail.app.

### Do I need a Google Cloud project to use Gmail with OpenClaw?

For the Gmail PubSub triggers, yes: they need gcloud, an authorized gog CLI and a public HTTPS endpoint. The IMAP trigger plugin works without Google Cloud. A hosted MCP server like Command Mail needs neither; Gmail reaches it through forwarding.

## Sources

1. [OpenClaw: Connect MCP servers](https://docs.openclaw.ai/tools/mcp), accessed 2026-10-28
2. [OpenClaw: Transports and OAuth](https://docs.openclaw.ai/cli/mcp/transports), accessed 2026-10-28
3. [OpenClaw: Manage saved MCP servers](https://docs.openclaw.ai/cli/mcp/registry), accessed 2026-10-28
4. [OpenClaw: Tool policy (MCP and plugin tools in the sandbox)](https://docs.openclaw.ai/gateway/config-tools/tool-policy), accessed 2026-10-28
5. [OpenClaw: IMAP email trigger](https://docs.openclaw.ai/automation/imap), accessed 2026-10-28
6. [OpenClaw: Gmail PubSub triggers](https://docs.openclaw.ai/automation/cron-jobs/gmail), accessed 2026-10-28
7. [OpenClaw: Himalaya skill (IMAP/SMTP)](https://github.com/openclaw/openclaw/blob/main/skills/himalaya/SKILL.md), accessed 2026-10-28
8. [OpenClaw: gog skill (Google Workspace CLI)](https://github.com/openclaw/openclaw/blob/main/skills/gog/SKILL.md), accessed 2026-10-28
9. [Command Mail: llms.txt with plans, permissions and setup](https://commandmail.app/llms.txt), accessed 2026-10-28
10. [OpenClaw: releases](https://github.com/openclaw/openclaw/releases), accessed 2026-10-28
11. [OpenClaw: Manage the Gateway service](https://docs.openclaw.ai/cli/gateway/service), accessed 2026-10-28

[^1]: [OpenClaw: Connect MCP servers](https://docs.openclaw.ai/tools/mcp), accessed 2026-10-28
[^2]: [OpenClaw: Transports and OAuth](https://docs.openclaw.ai/cli/mcp/transports), accessed 2026-10-28
[^3]: [OpenClaw: Manage saved MCP servers](https://docs.openclaw.ai/cli/mcp/registry), accessed 2026-10-28
[^4]: [OpenClaw: Tool policy (MCP and plugin tools in the sandbox)](https://docs.openclaw.ai/gateway/config-tools/tool-policy), accessed 2026-10-28
[^5]: [OpenClaw: IMAP email trigger](https://docs.openclaw.ai/automation/imap), accessed 2026-10-28
[^6]: [OpenClaw: Gmail PubSub triggers](https://docs.openclaw.ai/automation/cron-jobs/gmail), accessed 2026-10-28
[^7]: [OpenClaw: Himalaya skill (IMAP/SMTP)](https://github.com/openclaw/openclaw/blob/main/skills/himalaya/SKILL.md), accessed 2026-10-28
[^8]: [OpenClaw: gog skill (Google Workspace CLI)](https://github.com/openclaw/openclaw/blob/main/skills/gog/SKILL.md), accessed 2026-10-28
[^9]: [Command Mail: llms.txt with plans, permissions and setup](https://commandmail.app/llms.txt), accessed 2026-10-28
[^10]: [OpenClaw: releases](https://github.com/openclaw/openclaw/releases), accessed 2026-10-28
[^11]: [OpenClaw: Manage the Gateway service](https://docs.openclaw.ai/cli/gateway/service), accessed 2026-10-28

---

Command Mail: one inbox for you and your AI agent. Start free: https://commandmail.app/login?signup=1 · Connect your agent: https://commandmail.app/en/agents · MCP: https://commandmail.app/mcp