OpenClaw

Getting started

OpenClaw (formerly Moltbot) is an open-source AI personal assistant that runs on your own devices and integrates with messaging platforms like WhatsApp, Telegram, Discord, and Slack. By adding AgentMail to OpenClaw, your agent gains the ability to send and receive emails, enabling two-way email conversations alongside your existing chat channels.

AgentMail is published on ClawHub, the OpenClaw plugin registry, as an official plugin. The plugin is the recommended integration: it ships a CLI-backed AgentMail skill and registers email as an OpenClaw channel, so your agent can both send from an inbox and be reached at one.

Requirements

• OpenClaw 2026.7.2 (beta) or newer
• Node.js 22.22.3 to 22.x, 24.15.0 to 24.x, or 25.9.0+
• An AgentMail API key from the AgentMail Console

The published plugin bundles the official AgentMail CLI for macOS, Linux, and Windows. A separate global CLI install is not required.

Option 1: Official OpenClaw plugin (recommended)

AgentMail is listed on ClawHub under @agentmail with the Official badge. One command installs both the email skill and the email channel.

Installation

$
openclaw plugins install clawhub:@agentmail/agentmail
$
openclaw plugins enable agentmail

Configuration

Set AGENTMAIL_API_KEY in the environment that runs the OpenClaw Gateway. For a managed Gateway, put it in ~/.openclaw/.env so the channel and agent turns inherit the same credentials.

1
AGENTMAIL_API_KEY=am_...
2
AGENTMAIL_WEBHOOK_SECRET=whsec_...

AGENTMAIL_WEBHOOK_SECRET is optional and enables Svix-signed webhook ingress for the channel. Without it, the channel falls back to WebSocket ingress.

Restart and verify

$
openclaw gateway restart
$
openclaw plugins inspect agentmail --runtime

Optional: API base URL override

1
{
2
  plugins: {
3
    entries: {
4
      agentmail: {
5
        config: {
6
          baseUrl: "https://api.agentmail.to/v0",
7
        },
8
      },
9
    },
10
  },
11
}

The legacy timeoutSeconds and maxRetries settings are still accepted so existing configs keep loading, but the bundled CLI does not use them.

Email as an OpenClaw channel

The plugin registers email as an OpenClaw channel, alongside WhatsApp, Matrix, Discord, and Feishu. An inbound message to the agent’s inbox drives an agent turn, and the agent replies inside the same AgentMail thread.

Configure it under channels.agentmail for a single inbox, or channels.agentmail.accounts.<id> for several.

1
{
2
  channels: {
3
    agentmail: {
4
      apiKey: { source: "env", provider: "agentmail", id: "AGENTMAIL_API_KEY" },
5
      inboxId: "agent@agentmail.to",
6
      webhookSecret: { source: "env", provider: "agentmail", id: "AGENTMAIL_WEBHOOK_SECRET" },
7
      dmPolicy: "allowlist",
8
      allowFrom: ["person@example.com"],
9
      mediaMaxMb: 20,
10
    },
11
  },
12
}

Security defaults

• dmPolicy defaults to allowlist. An empty allowFrom denies every sender, so an unconfigured channel does nothing rather than accepting mail from anyone.
• dmPolicy: "open" requires allowFrom to include "*". Opening the channel is explicit.
• The channel is reply-only. The agent replies to the message that triggered it, with replyAll: false. It cannot start new threads or mail arbitrary recipients.
• Every reply re-hydrates the triggering message and re-authorizes its From header, so a forged Reply-To cannot redirect where the response goes.
• Inbound mail is committed durably before it is acknowledged, so a Gateway restart mid-turn does not lose the message.

The CLI-backed AgentMail skill

Rather than a fixed set of tool schemas, the plugin bundles the official AgentMail CLI and the agent reads its help output at runtime. New AgentMail API resources become usable without waiting for a plugin release.

The skill covers inboxes, messages, threads, drafts, webhooks, domains, pods, and API keys.

The plugin also registers a passthrough command you can run yourself. Keep the -- separator so OpenClaw forwards the following flags to AgentMail.

$
openclaw agentmail -- --help
$
$
openclaw agentmail -- --format json inboxes list
$
$
openclaw agentmail -- --format json inboxes:messages send \
>
  --inbox-id agent@agentmail.to \
>
  --to person@example.com \
>
  --subject "Hello" \
>
  --text "Hello from OpenClaw"

Features

The plugin includes:

• Email channel: inbound mail drives an agent turn; the agent replies in-thread. Default-deny sender allowlist, reply-only.
• CLI-backed skill: the agent reads the bundled AgentMail CLI’s help at runtime, so new API resources work without a plugin update.
• Inbox management: Create scalable inboxes on-demand with unique email addresses
• Message operations: Send emails with text and HTML content for best deliverability
• Thread management: Group related messages in conversations
• Attachments: Send and receive attachments with Base64 encoding
• Drafts: Create drafts for human-in-the-loop approval before sending
• Pods: Multi-tenant isolation for SaaS platforms
• Idempotency: Safe retries on create operations
• Real-time events: WebSocket and webhook support for notifications

Option 2: Skill only (for non-OpenClaw agents)

The standalone AgentMail skill still works and remains the right install for Claude Code, Cursor, and other skill-compatible agents. It does not include the email channel.

$
npx clawhub@latest install agentmail
$
# or, tool-agnostic
$
npx skills add agentmail-to/agentmail-skills

Skill configuration lives under skills.entries.agentmail.env in ~/.openclaw/openclaw.json:

1
{
2
  "skills": {
3
    "entries": {
4
      "agentmail": {
5
        "enabled": true,
6
        "env": {
7
          "AGENTMAIL_API_KEY": "your-api-key-here"
8
        }
9
      }
10
    }
11
  }
12
}

Get your API key from the AgentMail Console.

Check that the skill is loaded:

$
openclaw skills list --eligible

You should see agentmail in the list of available skills.

Option 3: Custom skill (advanced)

Most people should use the plugin above. Write a custom skill only if you need behaviour the plugin does not expose.

Skills are directories containing a SKILL.md file with instructions for OpenClaw.

Create the skill directory

Create a new skill in your OpenClaw workspace:

$
mkdir -p ~/.openclaw/skills/agentmail

Create the skill file

Create ~/.openclaw/skills/agentmail/SKILL.md with the following content:

1
---
2
name: agentmail
3
description: Send and receive emails using AgentMail
4
requires:
5
  env:
6
    - AGENTMAIL_API_KEY
7
---
8
9
# AgentMail Skill
10
11
You can send and receive emails using the AgentMail API. Use the `exec` tool to run curl commands against the AgentMail API.
12
13
## API Base URL
14
15
```
16
https://api.agentmail.to/v0
17
```
18
19
## Authentication
20
21
Include your API key in the Authorization header:
22
23
```
24
Authorization: Bearer $AGENTMAIL_API_KEY
25
```
26
27
## Common Operations
28
29
### List inboxes
30
31
```bash
32
curl -s -H "Authorization: Bearer $AGENTMAIL_API_KEY" \
33
  https://api.agentmail.to/v0/inboxes
34
```
35
36
### Create an inbox
37
38
```bash
39
curl -s -X POST -H "Authorization: Bearer $AGENTMAIL_API_KEY" \
40
  -H "Content-Type: application/json" \
41
  -d '{"display_name": "My Agent"}' \
42
  https://api.agentmail.to/v0/inboxes
43
```
44
45
### Send an email
46
47
```bash
48
curl -s -X POST -H "Authorization: Bearer $AGENTMAIL_API_KEY" \
49
  -H "Content-Type: application/json" \
50
  -d '{
51
    "to": ["recipient@example.com"],
52
    "subject": "Hello from OpenClaw",
53
    "text": "This email was sent by my AI assistant."
54
  }' \
55
  https://api.agentmail.to/v0/inboxes/{inbox_id}/messages/send
56
```
57
58
### List messages in an inbox
59
60
```bash
61
curl -s -H "Authorization: Bearer $AGENTMAIL_API_KEY" \
62
  https://api.agentmail.to/v0/inboxes/{inbox_id}/messages
63
```
64
65
### Reply to a message
66
67
```bash
68
curl -s -X POST -H "Authorization: Bearer $AGENTMAIL_API_KEY" \
69
  -H "Content-Type: application/json" \
70
  -d '{"text": "Thanks for your email!"}' \
71
  https://api.agentmail.to/v0/inboxes/{inbox_id}/messages/{message_id}/reply
72
```

Configure the skill

Add your AgentMail API key to the skill configuration in ~/.openclaw/openclaw.json:

1
{
2
  "skills": {
3
    "entries": {
4
      "agentmail": {
5
        "enabled": true,
6
        "env": {
7
          "AGENTMAIL_API_KEY": "your-api-key-here"
8
        }
9
      }
10
    }
11
  }
12
}

Verify the skill

Check that the skill is loaded:

$
openclaw skills list --eligible

You should see agentmail in the list of available skills.

Example use cases

With the email channel configured, you do not have to prompt the agent at all. Email the agent’s inbox from an allowlisted address and the message drives an agent turn directly. Forward it a thread with “draft me a reply to this” and the draft comes back in the same thread.

You can also ask your agent to:

• “Create a new email inbox for my project”
• “Check my inbox for new emails”
• “Send an email to john@example.com about the meeting tomorrow”
• “Reply to the latest email from Sarah”
• “Forward the invoice email to accounting@company.com”

Real-time email notifications

If you are using the email channel, ingress is already handled: set AGENTMAIL_WEBHOOK_SECRET and the channel receives Svix-signed webhooks, falling back to WebSocket if the secret is absent. The manual webhook setup below is for custom handling outside the channel.

For proactive email handling, you can combine AgentMail webhooks with OpenClaw’s webhook support. This allows OpenClaw to notify you immediately when new emails arrive.

1. Set up a webhook endpoint in OpenClaw (see OpenClaw webhook documentation)

2. Register the webhook with AgentMail:

$
curl -X POST -H "Authorization: Bearer $AGENTMAIL_API_KEY" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "url": "https://your-openclaw-webhook-url",
>
    "event_types": ["message.received"]
>
  }' \
>
  https://api.agentmail.to/v0/webhooks

Now OpenClaw will be notified whenever a new email arrives, allowing it to proactively inform you or take action.

FAQ

Resources

• AgentMail on ClawHub
• AgentMail Skill (all agents)
• AgentMail API Reference
• OpenClaw plugin documentation
• OpenClaw Documentation
• OpenClaw Skills Guide