romtuck/openclaw
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs

Browse Source
This commit is contained in:
Haakam Aujla 2026-01-27 17:52:33 -08:00
parent 06e0d7fc9c
commit c9a2129f43
3 changed files with 109 additions and 79 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

178
docs/channels/agentmail.md
View File

@ -6,58 +6,29 @@ read_when:
# AgentMail # AgentMail
AgentMail is an email API service designed for AI agents. Clawdbot connects to AgentMail via AgentMail is an email API service designed for AI agents. Moltbot connects to AgentMail via
webhooks to receive incoming emails and uses the AgentMail API to send replies. This enables WebSockets to receive incoming emails in real-time and uses the AgentMail API to send replies.
email as a conversation channel for your AI assistant. This enables email as a conversation channel for your AI assistant.
Status: supported via plugin. Direct messages (email threads), media (attachments as links), Status: supported as a core channel. Direct messages (email threads), media (attachments as links),
and threading are supported. and threading are supported.
## Plugin required ## Quick setup
AgentMail ships as a plugin and is not bundled with the core install. 1. Create an AgentMail account at [agentmail.to](https://agentmail.to) (free to sign up)
2. Get your API token from the AgentMail dashboard
Install via CLI (npm registry): 3. Run onboarding or configure manually:
```bash ```bash
clawdbot plugins install @clawdbot/agentmail moltbot onboard
# Select AgentMail and follow the prompts
``` ```
Local checkout (when running from a git repo): Or set credentials directly:
- Env: `AGENTMAIL_TOKEN`, `AGENTMAIL_EMAIL_ADDRESS`
- Or config: `channels.agentmail.token`, `channels.agentmail.emailAddress`
```bash 4. Start the gateway
clawdbot plugins install ./extensions/agentmail
```
Details: [Plugins](/plugin)
## 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](https://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: Minimal config:
@ -73,17 +44,33 @@ Minimal config:
} }
``` ```
## How it works
1. The gateway connects to AgentMail via WebSocket on startup
2. When an email arrives at your inbox, AgentMail pushes a real-time event
3. Moltbot fetches the full thread for context and routes to the agent
4. The agent's reply is sent via the AgentMail API (reply-all to preserve recipients)
No public URL or webhook setup required - WebSocket connections are outbound only.
## Configuration ## Configuration
| Key | Type | Description | | Key | Type | Description |
| -------------- | -------- | -------------------------------------------------------- | | -------------- | -------- | --------------------------------------------------- |
| `name` | string | Account name for identifying this configuration | | `name` | string | Account name for identifying this configuration |
| `enabled` | boolean | Enable/disable the channel (default: true) | | `enabled` | boolean | Enable/disable the channel (default: true) |
| `token` | string | AgentMail API token (required) | | `token` | string | AgentMail API token (required) |
| `emailAddress` | string | AgentMail inbox email address to monitor (required) | | `emailAddress` | string | AgentMail inbox email address to monitor (required) |
| `webhookUrl` | string | Full public webhook URL (e.g., `https://gw.ngrok.io/webhooks/agentmail`) | | `allowFrom` | string[] | Allowed sender emails/domains (empty = allow all) |
| `webhookPath` | string | Local webhook path (derived from URL or default: `/webhooks/agentmail`) |
| `allowFrom` | string[] | Allowed sender emails/domains (empty = allow all) | ## Environment Variables
| Variable | Description |
| ------------------------- | ----------------------------- |
| `AGENTMAIL_TOKEN` | AgentMail API token |
| `AGENTMAIL_EMAIL_ADDRESS` | AgentMail inbox email address |
If both env and config are set, config takes precedence.
## Sender Filtering ## Sender Filtering
@ -92,7 +79,7 @@ AgentMail uses `allowFrom` to filter incoming emails. The list accepts email add
### Filtering Logic ### Filtering Logic
1. If `allowFrom` is empty, all senders are allowed (open mode) 1. If `allowFrom` is empty, all senders are allowed (open mode)
2. If `allowFrom` is non-empty, only matching senders trigger Clawdbot 2. If `allowFrom` is non-empty, only matching senders trigger Moltbot
3. Allowed messages are labeled `allowed` in AgentMail 3. Allowed messages are labeled `allowed` in AgentMail
4. Non-matching senders are silently ignored 4. Non-matching senders are silently ignored
@ -120,39 +107,34 @@ Domain entries match any email from that domain:
## Thread Context ## Thread Context
When an email arrives, Clawdbot fetches the full email thread to provide conversation context When an email arrives, Moltbot 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 to the AI. This enables the assistant to understand prior messages in the thread and provide
contextually relevant replies. contextually relevant replies.
Thread context is automatically included when: Thread context includes:
- Subject line
- The incoming email is part of an existing thread - All senders and recipients
- The thread has more than one message - Message history with timestamps
- Attachment metadata (filenames, sizes, types)
The plugin uses AgentMail's `extracted_text` field which contains only the new content from 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 each message (excluding quoted reply text). This provides cleaner context without duplicated
quoted sections. quoted sections.
## Environment Variables ## Reply Behavior
| Variable | Description | Moltbot uses **reply-all** when responding to emails. This ensures all original recipients
| -------------------------- | ----------------------------- | (To, Cc) receive the reply, maintaining proper email thread etiquette.
| `AGENTMAIL_TOKEN` | AgentMail API token |
| `AGENTMAIL_EMAIL_ADDRESS` | AgentMail inbox email address |
| `AGENTMAIL_WEBHOOK_PATH` | Custom webhook path |
## Webhook Security ## WebSocket Connection
AgentMail webhooks should be configured with HTTPS endpoints. Ensure your gateway is The AgentMail channel uses WebSockets for real-time message delivery:
accessible from the internet and properly secured.
For local development, you can use tools like ngrok to tunnel webhooks to your local machine: - **Automatic reconnection**: The SDK handles reconnection with up to 30 retry attempts
- **Resubscription**: On reconnect, the channel automatically resubscribes to inbox events
- **No public URL needed**: WebSocket connections are outbound-only, no firewall configuration required
```bash Connection status is visible in gateway logs and `moltbot channels status`.
ngrok http 18789
```
Then register the ngrok URL as your webhook endpoint in the AgentMail dashboard.
## Capabilities ## Capabilities
@ -165,23 +147,61 @@ Then register the ngrok URL as your webhook endpoint in the AgentMail dashboard.
| Reactions | No | | Reactions | No |
| Polls | No | | Polls | No |
## Agent Tools
The AgentMail channel provides tools for the agent to interact with email:
- List and search threads
- Read message content and attachments
- Send new emails
- Reply to existing threads
- Manage labels
Tools are provided by the [AgentMail Toolkit](https://github.com/nicholasgriffintn/agentmail-toolkit).
## Troubleshooting ## Troubleshooting
### Messages not being received ### Messages not being received
1. Verify the webhook is registered in AgentMail dashboard 1. Verify the API token is valid (check AgentMail dashboard)
2. Check that the webhook URL is correct and accessible 2. Confirm the email address matches an inbox you own
3. Ensure `token` and `emailAddress` are configured correctly 3. Check gateway logs for WebSocket connection errors
4. Check the gateway logs for webhook errors 4. Run `moltbot channels status --probe` to verify connectivity
### WebSocket connection issues
1. Check network connectivity to AgentMail servers
2. Look for `WebSocket closed` or `WebSocket error` in logs
3. The SDK auto-reconnects; persistent failures indicate token or network issues
### Replies not being sent ### Replies not being sent
1. Verify the API token has send permissions 1. Verify the API token has send permissions
2. Check the gateway logs for outbound errors 2. Check the gateway logs for outbound errors
3. Ensure the email address is correct 3. Ensure the email address is correctly configured
### Sender not allowed ### Sender not allowed
1. Check the `allowFrom` configuration 1. Check the `allowFrom` configuration
2. Verify the sender email matches an entry in allowFrom 2. Verify the sender email matches an entry in allowFrom (exact email or domain)
3. Remember: empty allowFrom means all senders are allowed 3. Remember: empty allowFrom means all senders are allowed
### Connection keeps reconnecting
1. Check if the API token is valid and not expired
2. Verify the inbox exists in your AgentMail account
3. Check for network issues or firewall blocking outbound WebSocket connections
## Status and Probing
Check channel status:
```bash
moltbot channels status
moltbot channels status --probe # includes API connectivity test
```
The probe verifies:
- API token is valid
- Inbox exists and is accessible
- WebSocket connection can be established

1
docs/channels/index.md
View File

@ -15,6 +15,7 @@ Text is supported everywhere; media and reactions vary by channel.
- [Telegram](/channels/telegram) — Bot API via grammY; supports groups. - [Telegram](/channels/telegram) — Bot API via grammY; supports groups.
- [Discord](/channels/discord) — Discord Bot API + Gateway; supports servers, channels, and DMs. - [Discord](/channels/discord) — Discord Bot API + Gateway; supports servers, channels, and DMs.
- [Slack](/channels/slack) — Bolt SDK; workspace apps. - [Slack](/channels/slack) — Bolt SDK; workspace apps.
- [AgentMail](/channels/agentmail) — Email via AgentMail API; WebSocket-based real-time delivery.
- [Google Chat](/channels/googlechat) — Google Chat API app via HTTP webhook. - [Google Chat](/channels/googlechat) — Google Chat API app via HTTP webhook.
- [Mattermost](/channels/mattermost) — Bot API + WebSocket; channels, groups, DMs (plugin, installed separately). - [Mattermost](/channels/mattermost) — Bot API + WebSocket; channels, groups, DMs (plugin, installed separately).
- [Signal](/channels/signal) — signal-cli; privacy-focused. - [Signal](/channels/signal) — signal-cli; privacy-focused.

9
docs/docs.json
View File

@ -149,6 +149,14 @@
"source": "/message/", "source": "/message/",
"destination": "/cli/message" "destination": "/cli/message"
}, },
{
"source": "/providers/agentmail",
"destination": "/channels/agentmail"
},
{
"source": "/providers/agentmail/",
"destination": "/channels/agentmail"
},
{ {
"source": "/providers/discord", "source": "/providers/discord",
"destination": "/channels/discord" "destination": "/channels/discord"
@ -986,6 +994,7 @@
"channels/telegram", "channels/telegram",
"channels/grammy", "channels/grammy",
"channels/discord", "channels/discord",
"channels/agentmail",
"channels/slack", "channels/slack",
"channels/googlechat", "channels/googlechat",
"channels/mattermost", "channels/mattermost",