# Send & Receive Emails with OpenClaw (/integrations/frameworks/openclaw) Related: [Send & Receive Emails with Claude Cowork](/integrations/frameworks/claude-cowork.md), [Send & Receive Emails with Claude Code](/integrations/frameworks/claude-code.md), [Send & Receive Emails with OpenAI Codex](/integrations/frameworks/codex.md), [Send & Receive Emails with Grok](/integrations/frameworks/grok.md), [Send & Receive Emails with Manus](/integrations/frameworks/manus.md), [Send & Receive Emails with Cursor](/integrations/frameworks/cursor.md) # Give an OpenClaw agent email with the AgentMail plugin The official AgentMail plugin on ClawHub adds two surfaces to OpenClaw: a CLI-backed skill the agent uses to create inboxes and send email, and an email channel that turns inbound mail into agent turns with replies in the same thread. Use it when an OpenClaw agent should send from its own address or be reachable at an allowlisted one. ## Do this 1. Generate an API key at `https://console.agentmail.to/dashboard/api-keys` and put it in the environment that runs the OpenClaw Gateway. For a managed Gateway that is `~/.openclaw/.env`: ```dotenv AGENTMAIL_API_KEY= # Optional. Enables signed webhook ingress for the email channel. AGENTMAIL_WEBHOOK_SECRET= ``` 2. Install and enable the plugin, then restart the Gateway so it loads: ```bash openclaw plugins install clawhub:@agentmail/agentmail openclaw plugins enable agentmail openclaw gateway restart ``` 3. List inboxes with `openclaw agentmail -- --format json inboxes list`. If the list is empty, create one (omit `--username` to let AgentMail generate one) and save the `inbox_id` from the response: ```bash openclaw agentmail -- --format json inboxes create \ --username support-agent \ --display-name "Support agent" ``` 4. Send a test email from the agent's inbox: ```bash openclaw agentmail -- --format json inboxes:messages send \ --inbox-id "" \ --to "you@example.com" \ --subject "Hello from OpenClaw" \ --text "First email from my agent." ``` 5. To let inbound email drive the agent, configure the channel under `channels.agentmail` in `~/.openclaw/openclaw.json`, then restart the Gateway: ```json5 { channels: { agentmail: { apiKey: { source: "env", provider: "default", id: "AGENTMAIL_API_KEY" }, inboxId: "faircost773@agentmail.to", webhookSecret: { source: "env", provider: "default", id: "AGENTMAIL_WEBHOOK_SECRET" }, dmPolicy: "allowlist", allowFrom: ["you@example.com"], mediaMaxMb: 20, }, }, } ``` 6. From an address in `allowFrom`, email the agent's inbox. The message drives an agent turn with no prompting, and the reply arrives in the same email thread from the agent's address. ## Facts * Install source: ClawHub, the OpenClaw package registry. Keep the `clawhub:` prefix in `openclaw plugins install clawhub:@agentmail/agentmail` so OpenClaw resolves the package on ClawHub instead of npm, git, or a local path. * The plugin bundles the AgentMail CLI for macOS, Linux, and Windows. The ClawHub listing at `https://clawhub.ai/agentmail/plugins/agentmail` states the supported OpenClaw and Node.js versions. * Both the email channel and the CLI-backed skill authenticate with `AGENTMAIL_API_KEY` from the Gateway environment. A different key or API base URL goes in `plugins.entries.agentmail.config` in `~/.openclaw/openclaw.json` (`apiKey` plus `baseUrl: "https://api.agentmail.to/v0"`). * Passthrough syntax: `openclaw agentmail -- `. Everything after `--` is forwarded to the bundled AgentMail CLI, which runs on the OpenClaw host. A sandboxed agent needs permission to execute it there. * The skill reads the bundled CLI's help at runtime. It covers inboxes, messages, threads, drafts, webhooks, domains, pods, and API keys, and new AgentMail resources work without a plugin update. * A send returns `message_id` and `thread_id`. Use `thread_id` to follow up in the same thread. * Requesting a taken username returns `403` with up to 3 currently available variants of the name in `suggestions`. * With `AGENTMAIL_WEBHOOK_SECRET` set, the channel receives Svix-signed webhooks. Without it, the channel falls back to WebSocket ingress. Mail reaches the agent either way, with no polling loop. * `dmPolicy` defaults to `allowlist`. An empty `allowFrom` denies every sender. `dmPolicy: "open"` accepts mail from anyone and requires `allowFrom` to include `"*"`. * Every reply re-authorizes the `From` of the message that triggered it, so a forged `Reply-To` does not change where the reply goes. * Inbound mail is committed durably before it is acknowledged. A Gateway restart mid-turn does not lose the message. * Several inboxes: configure each one under `channels.agentmail.accounts.`. * `mediaMaxMb` caps attachment size in MB. * Keep the casing of `inboxId` stable across config changes. It identifies the channel's durable receive queue, and changing only the case can deliver already-handled messages one more time. * On hosts that discover `SKILL.md` instructions (Claude Code, Cursor, Codex), install the standalone skill with `npx skills add agentmail-to/agentmail-skills` instead of the plugin. On an OpenClaw host, `openclaw skills list --eligible` should list `agentmail`. ## Not supported * Passthrough arguments cannot override `--api-key`, `--base-url`, or `--environment`, and inherited proxy variables such as `HTTP_PROXY` and `HTTPS_PROXY` are stripped. An argument whose value must literally start with `--base-url` or `--environment` needs `--option=value` form, for example `--subject=--base-url-is-restricted`. * The CLI ignores API keys inherited from the process that invokes it. Only the Gateway environment or the plugin config supplies the key. * An `apiKey` set only under `channels.agentmail` configures the channel alone and leaves the CLI-backed skill without a credential. * The channel is reply-only, with `replyAll: false`. A channel turn answers the message that triggered it. New email to other recipients goes through the CLI-backed skill. ## Errors | Error | Status | Cause | Fix | | ---------------- | ------ | ------------------------------------------------------------------------ | -------------------------------------------------------------------- | | `resource_taken` | 403 | The requested inbox username belongs to another organization. | Retry with one of the up to 3 variants in `suggestions`. | | `already_exists` | 403 | An inbox with the requested username already exists in the organization. | Retry with a username from `suggestions`, or use the existing inbox. | ## Verify ```bash openclaw plugins inspect agentmail --runtime ``` This loads the plugin and reports the surfaces it registered, including the `agentmail` command. Then `openclaw agentmail -- --format json inboxes list` returning a `count` and an `inboxes` array confirms the credential works end to end. ## Related * [Agent safety](/advanced/safety): the inbound-safety model behind the channel's allowlist and reply-only defaults. * [MCP and Skills](/integrations/mcp-and-skills): skill and MCP options for Claude Code, Cursor, Codex, and other agent hosts. * [Quickstart](/quickstart): keys and inboxes for readers new to AgentMail.