Send & Receive Emails with OpenClaw

OpenClaw is an open-source AI assistant that runs on your own hardware and talks to you over chat channels such as WhatsApp, Telegram, and Discord. AgentMail publishes an official plugin for it on ClawHub, the OpenClaw package registry. The plugin adds two surfaces: a CLI-backed skill your agent uses to create inboxes and send email, and an email channel so inbound mail can drive the agent directly.

0. Get an API key

Generate an API key from the AgentMail Console. If you are new to AgentMail, the Quickstart walks through keys and inboxes first.

Put the key in the environment that runs the OpenClaw Gateway. For a managed Gateway, that is ~/.openclaw/.env:

AGENTMAIL_API_KEY=<API_KEY>
# Optional. Enables signed webhook ingress for the email channel in step 3.
AGENTMAIL_WEBHOOK_SECRET=<WEBHOOK_SECRET>

The plugin bundles the AgentMail CLI for macOS, Linux, and Windows, so this key is the only credential you manage. Check the ClawHub listing for the OpenClaw and Node.js versions the current plugin release supports.

1. Install the plugin

Install and enable the plugin from ClawHub, then restart the Gateway so it loads:

openclaw plugins install clawhub:@agentmail/agentmail
openclaw plugins enable agentmail
openclaw gateway restart

Keep the clawhub: prefix. It makes OpenClaw resolve the package on ClawHub instead of npm, git, or a local path.

Confirm the Gateway loads the plugin:

openclaw plugins inspect agentmail --runtime

inspect --runtime loads the plugin and reports the surfaces it registered, including the agentmail command you will use in the next step.

The bundled CLI takes its key from the plugin entry in ~/.openclaw/openclaw.json and ignores keys inherited from the process that invokes it. Point the entry at the AGENTMAIL_API_KEY you set in the Gateway environment.

{
  plugins: {
    entries: {
      agentmail: {
        config: {
          apiKey: { source: "env", provider: "default", id: "AGENTMAIL_API_KEY" },
        },
      },
    },
  },
}

To point the CLI at a different API host, add baseUrl next to apiKey. The CLI appends the /v0 version prefix itself, so pass the bare host, for example "https://api.agentmail.to".

2. Test sending emails

The plugin registers a passthrough command for the bundled CLI. Keep the -- separator: OpenClaw forwards everything after it to AgentMail.

List your inboxes to find the address your agent will send from:

openclaw agentmail -- --format json inboxes list

{
  "count": 1,
  "inboxes": [
    {
      "organization_id": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d",
      "pod_id": "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d",
      "inbox_id": "faircost773@agentmail.to",
      "email": "faircost773@agentmail.to",
      "display_name": "Support agent",
      "updated_at": "2026-08-23T09:26:01.279Z",
      "created_at": "2026-08-23T09:26:01.279Z"
    }
  ]
}

If the list is empty, create an inbox. Pick a --username for the part before the @, or omit it and AgentMail generates one. Save the inbox_id from the response.

openclaw agentmail -- --format json inboxes create \
  --username support-agent \
  --display-name "Support agent"

Usernames are first come, first served.

Now send a test email from your agent’s inbox to an email account you already check. It should be there moments after the command returns:

openclaw agentmail -- --format json inboxes:messages send \
  --inbox-id "<inbox_id>" \
  --to "you@example.com" \
  --subject "Hello from OpenClaw" \
  --text "First email from my agent."

{
  "message_id": "<010001a02e069a11-3c52b1de-91f7-4d02-b1cd-6a2e40c3f7aa-000000@email.amazonses.com>",
  "thread_id": "7d54a1cf-20b8-4e19-9d63-52c40a8e2b91"
}

The send returns the message’s message_id and the thread_id of the conversation it starts. Your agent uses these to follow up in the same thread.

For credential safety, the passthrough rejects --api-key, --base-url, and --environment overrides, and it strips inherited proxy variables such as HTTP_PROXY and HTTPS_PROXY. If an argument’s value is itself --base-url or --environment, or starts with --base-url= or --environment=, pass it in --option=value form, for example --subject=--base-url.

You can also skip the commands and ask the agent directly, for example “send an email to you@example.com about tomorrow’s meeting”. 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. The command runs on the OpenClaw host, so a sandboxed agent needs permission to execute it there.

3. Turn email into an OpenClaw channel

Sending is agent-initiated. In the other direction, an email to your agent’s inbox drives an agent turn, the same way a WhatsApp or Discord message does, and the agent replies inside the same email thread.

Configure the channel under channels.agentmail in ~/.openclaw/openclaw.json, then restart the Gateway:

{
  channels: {
    agentmail: {
      apiKey: { source: "env", provider: "default", id: "AGENTMAIL_API_KEY" },
      inboxId: "faircost773@agentmail.to", // the inbox from step 2
      webhookSecret: { source: "env", provider: "default", id: "AGENTMAIL_WEBHOOK_SECRET" },
      dmPolicy: "allowlist",
      allowFrom: ["you@example.com"], // senders allowed to reach the agent
      mediaMaxMb: 20, // attachment size cap in MB
    },
  },
}

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.

To run several inboxes, configure each one under channels.agentmail.accounts.<id>.

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.

4. Test receiving and replying

From an address in allowFrom, send an email to your agent’s inbox. Give it a subject and a question the agent can answer.

The message drives an agent turn with no prompting on your side, and the reply arrives in the same email thread, from the agent’s address.

The channel is locked down by default:

• dmPolicy defaults to allowlist. An empty allowFrom denies every sender, so an unconfigured channel accepts no one.
• dmPolicy: "open" accepts mail from anyone and requires allowFrom to include "*". Opening the channel is explicit.
• 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 instead.
• 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, so a Gateway restart mid-turn does not lose the message.

Use the skill without the plugin

Use the plugin on OpenClaw. For hosts that discover SKILL.md instructions, such as Claude Code, Cursor, and Codex, install with:

npx skills add agentmail-to/agentmail-skills

The installer asks which host to target. On an OpenClaw host, verify with openclaw skills list --eligible: the list should include agentmail. For the full skill and MCP options, see MCP and Skills.

Next Steps