openclaw/docs/channels/agentmail.md

summary	read_when
AgentMail email channel support, capabilities, and configuration	Working on AgentMail/email channel features

AgentMail

AgentMail is an email API service designed for AI agents. Clawdbot connects to AgentMail via webhooks to receive incoming emails and uses the AgentMail API to send replies. This enables email as a conversation channel for your AI assistant.

Status: supported via plugin. Direct messages (email threads), media (attachments as links), and threading are supported.

Plugin required

AgentMail ships as a plugin and is not bundled with the core install.

Install via CLI (npm registry):

clawdbot plugins install @clawdbot/agentmail

Local checkout (when running from a git repo):

clawdbot plugins install ./extensions/agentmail

Details: Plugins

Setup

1. Install the AgentMail plugin:

   • From npm: clawdbot plugins install @clawdbot/agentmail
   • From a local checkout: clawdbot plugins install ./extensions/agentmail

2. Create an AgentMail account at agentmail.to

3. Get your API key from the AgentMail dashboard

4. Create an inbox (or use an existing one) and note the inbox ID

5. Webhook setup:

   • Automatic: During onboarding, provide your gateway's public URL and the webhook will be auto-registered
   • Manual: Register in the AgentMail dashboard with URL https://your-gateway/webhooks/agentmail and event type message.received

6. Configure credentials:

   • Env: AGENTMAIL_TOKEN, AGENTMAIL_EMAIL_ADDRESS
   • Or config: channels.agentmail.token, channels.agentmail.emailAddress
   • If both are set, config takes precedence.

7. Restart the gateway (or finish onboarding)

8. Send an email to your AgentMail inbox to test the integration

Minimal config:

{
  channels: {
    agentmail: {
      enabled: true,
      token: "am_***",
      emailAddress: "you@agentmail.to",
    },
  },
}

Configuration

Key	Type	Description
name	string	Account name for identifying this configuration
enabled	boolean	Enable/disable the channel (default: true)
token	string	AgentMail API token (required)
emailAddress	string	AgentMail inbox email address to monitor (required)
webhookUrl	string	Gateway public base URL (e.g., https://gw.ngrok.io)
webhookPath	string	Custom webhook path (default: /webhooks/agentmail)
allowFrom	string[]	Allowed sender emails/domains (empty = allow all)

Sender Filtering

AgentMail uses allowFrom to filter incoming emails. The list accepts email addresses and domains.

Filtering Logic

1. If allowFrom is empty, all senders are allowed (open mode)
2. If allowFrom is non-empty, only matching senders trigger Clawdbot
3. Allowed messages are labeled allowed in AgentMail
4. Non-matching senders are silently ignored

Example Configuration

{
  channels: {
    agentmail: {
      enabled: true,
      token: "am_***",
      emailAddress: "clawd@agentmail.to",
      // Allow specific emails and domains
      allowFrom: ["alice@example.com", "trusted-domain.org"],
    },
  },
}

Domain Matching

Domain entries match any email from that domain:

• example.org in allowFrom allows alice@example.org, bob@example.org, etc.

Thread Context

When an email arrives, Clawdbot fetches the full email thread to provide conversation context to the AI. This enables the assistant to understand prior messages in the thread and provide contextually relevant replies.

Thread context is automatically included when:

• The incoming email is part of an existing thread
• The thread has more than one message

The plugin uses AgentMail's extracted_text field which contains only the new content from each message (excluding quoted reply text). This provides cleaner context without duplicated quoted sections.

Environment Variables

Variable	Description
AGENTMAIL_TOKEN	AgentMail API token
AGENTMAIL_EMAIL_ADDRESS	AgentMail inbox email address
AGENTMAIL_WEBHOOK_PATH	Custom webhook path

Webhook Security

AgentMail webhooks should be configured with HTTPS endpoints. Ensure your gateway is accessible from the internet and properly secured.

For local development, you can use tools like ngrok to tunnel webhooks to your local machine:

ngrok http 18789

Then register the ngrok URL as your webhook endpoint in the AgentMail dashboard.

Capabilities

Feature	Supported
Direct messages	Yes
Groups/rooms	No
Threads	Yes
Media (attachments)	Partial (links only)
Reactions	No
Polls	No

Troubleshooting

Messages not being received

1. Verify the webhook is registered in AgentMail dashboard
2. Check that the webhook URL is correct and accessible
3. Ensure token and emailAddress are configured correctly
4. Check the gateway logs for webhook errors

Replies not being sent

1. Verify the API token has send permissions
2. Check the gateway logs for outbound errors
3. Ensure the email address is correct

Sender not allowed

1. Check the allowFrom configuration
2. Verify the sender email matches an entry in allowFrom
3. Remember: empty allowFrom means all senders are allowed