# Give your OpenClaw agent an email address The Groundmail plugin for OpenClaw gives your agent its own email address. People email it and it answers in the same thread. Sign-up codes and other automated mail reach it on their own, so it can get past a "check your email" step without you. **Package:** [`@groundmail/openclaw`](https://www.npmjs.com/package/@groundmail/openclaw) · **Needs:** OpenClaw 2026.11.3 or later --- ## 1. Install ```bash openclaw plugins install @groundmail/openclaw openclaw channels add --channel groundmail openclaw gateway restart ``` With no key, `channels add` creates an address with no account, such as `bot-7f2k@agents.groundmailbox.com`, and stores a key that reaches only that mailbox. Email it and the agent answers. | Flag | What it does | |------|--------------| | `--local-part sales` | Choose the name before the `@` | | `--owner-email you@example.com` | Name the person behind the agent, so it can send (see below) | | `--api-key gm_…` | Use your Groundmail account instead (see below) | | `--mailbox
` | Use a mailbox you already have | | `--mode channel\|notify\|tool` | How new mail reaches the agent (see below) | ### Let a no-account address send An address made with no account can receive straight away, but it can't send until you name its person: 1. Pass `--owner-email you@example.com` to `channels add`, or later run `openclaw groundmail -- mailboxes owner
--owner-email you@example.com`. 2. We email you a 6-digit code. Until you use it, the agent can email only you, 10 a day. 3. Give the code to the agent, or run `openclaw groundmail -- mailboxes verify
--code 482913`. From then on it's a normal mailbox. Addresses that are never verified are deleted after 30 days, or after 7 with no mail. ### Use your Groundmail account Pass an API key from **API keys** in the dashboard: ```bash openclaw channels add --channel groundmail --api-key gm_… --local-part support ``` OpenClaw uses the mailbox you name with `--mailbox`, creates one with `--local-part`, or picks your only one. It then makes a new key that reaches only that mailbox and stores that one: your account key is never written to the config. See [Limit a key to mailboxes](https://docs.groundmail.dev/api-keys#limit-a-key-to-mailboxes). ## 2. What reaches the agent | Mode | Mail from people | Automated mail (sign-up codes, notifications, no-reply senders) | |------|------------------|----------------------------------------------------------------| | `channel` (default) | Wakes the agent; its answer goes back in the same thread | A short note in the agent's main chat; no reply is sent | | `notify` | A short note in the agent's main chat to tell you about; no reply | Same | | `tool` | Nothing arrives on its own | Nothing arrives on its own | The agent only answers mail that passed DMARC, so a reply never goes to a forged sender. [Held mail](https://docs.groundmail.dev/mailboxes#held-mail) (spam, floods, senders you blocked) never reaches it. Each person who writes is their own conversation, and the agent's reply keeps the thread: `Re:` subject and threading headers included. ## 3. Every email is untrusted Anyone who knows the address can write to your agent, so treat its mail like any input from a stranger. The plugin: - Hands the agent what a person would see, with hidden text removed and quoted history left out. - Puts the email between markers, labelled as written by someone outside, so it reads as information and not as instructions. - Pulls out the one-time code and the links, so the agent doesn't have to parse the body. - Adds a warning when the email looks like it's trying to give the agent instructions. - Keeps the body out of the agent's main chat, where it has its full context and tools. Notes there say only that an email arrived, with the one-time code if there is one: nothing the sender wrote, not even the subject. The agent reads the email with `openclaw groundmail -- mailboxes read` when you ask. Decide what the agent may do before it reads mail. More in [Mail is untrusted](https://docs.groundmail.dev/mailboxes#mail-is-untrusted). ## 4. More than replies The plugin adds a command that runs the [Groundmail CLI](https://docs.groundmail.dev/cli) with the channel's key, so the agent never sees the key, and a skill that teaches the agent to use it: ```bash # Wait for a sign-up code: take the time first, then trigger the email openclaw groundmail -- mailboxes wait
--since 2026-11-14T10:00:00.000Z --timeout 60 --json # Read a whole thread, or search openclaw groundmail -- mailboxes read
thd_… --json openclaw groundmail -- mailboxes read
--search "invoice" --json # Email someone first (needs a mailbox on your own domain) openclaw groundmail -- mailboxes send
--to person@example.com --subject "…" --text "…" ``` `--api-key` and `--base-url` can't be passed to this command: they always come from the channel config. An address on the shared agent domain can reply, but not email people first. For that, create the mailbox on [your own domain](https://docs.groundmail.dev/domains). ## 5. Configuration `channels add` writes this for you. To set it by hand: ```json5 { channels: { groundmail: { // A literal key, or a SecretRef so it stays out of openclaw.json apiKey: { source: "env", provider: "default", id: "GROUNDMAIL_API_KEY" }, mailbox: "support@agents.example.com", mode: "channel", }, }, } ``` For several agents, add accounts under `channels.groundmail.accounts.`, each with its own `mailbox` and `apiKey`, and bind them to agents as usual. No webhook or open port is needed: the gateway holds a long poll to Groundmail and picks up where it left off after a restart. It works on a laptop or behind NAT. ## Troubleshooting - **`openclaw channels status` shows Groundmail as not configured:** run `openclaw channels add --channel groundmail` again. - **The gateway log says Groundmail refused the account:** the key was deleted or doesn't reach the mailbox. Run `channels add` with a new key. - **The agent's reply wasn't sent:** an address made with no account can't send until you [name its person](#let-a-no-account-address-send). Hosted addresses can only reply, and never to a sender who failed DMARC. Related: [Mailboxes API](https://docs.groundmail.dev/mailboxes) · [Give your agent an email address](https://docs.groundmail.dev/guides/agent-mailboxes) · [Agent Skills](https://docs.groundmail.dev/ai/agent-skills)