Give your OpenClaw agent an email address

Package: @groundmail/openclaw · Needs: OpenClaw 2026.11.3 or later

Install

Terminal

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

Pass --owner-email you@example.com to channels add, or later run openclaw groundmail -- mailboxes owner <address> --owner-email you@example.com.
We email you a 6-digit code. Until you use it, the agent can email only you, 10 a day.
Give the code to the agent, or run openclaw groundmail -- mailboxes verify <address> --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:

Terminal

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.

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 (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.

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.

More than replies

The plugin adds a command that runs the Groundmail CLI with the channel's key, so the agent never sees the key, and a skill that teaches the agent to use it:

Terminal

# Wait for a sign-up code: take the time first, then trigger the email
openclaw groundmail -- mailboxes wait <address> --since 2026-11-14T10:00:00.000Z --timeout 60 --json

# Read a whole thread, or search
openclaw groundmail -- mailboxes read <address> thd_… --json
openclaw groundmail -- mailboxes read <address> --search "invoice" --json

# Email someone first (needs a mailbox on your own domain)
openclaw groundmail -- mailboxes send <address> --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.

Configuration

channels add writes this for you. To set it by hand:

{
  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.<id>, 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. Hosted addresses can only reply, and never to a sender who failed DMARC.