openclaw-agentmail-listener 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +103 -0
- package/dist/index.js +13190 -0
- package/dist/index.js.map +7 -0
- package/openclaw.plugin.json +64 -0
- package/package.json +48 -0
package/README.md
ADDED
|
@@ -0,0 +1,103 @@
|
|
|
1
|
+
# openclaw-agentmail
|
|
2
|
+
|
|
3
|
+
An [OpenClaw](https://openclaw.dev) plugin that listens for incoming emails via [AgentMail](https://agentmail.to) WebSocket and injects system events so your AI agent can act on them.
|
|
4
|
+
|
|
5
|
+
## What it does
|
|
6
|
+
|
|
7
|
+
- Registers a background service at gateway startup
|
|
8
|
+
- Connects to AgentMail via WebSocket
|
|
9
|
+
- Subscribes to a configured inbox (e.g. `nickbot@agentmail.to`)
|
|
10
|
+
- When a `message.received` event fires, injects a system event via `core.system.enqueueSystemEvent()` with email metadata (from, subject, preview)
|
|
11
|
+
- Auto-reconnects with exponential backoff on disconnect
|
|
12
|
+
- Stops cleanly when the gateway shuts down
|
|
13
|
+
|
|
14
|
+
This is **not** a channel plugin — it doesn't handle replies. It just triggers system events so the agent notices new emails and can decide what to do (e.g. read the full message via the AgentMail skill and reply).
|
|
15
|
+
|
|
16
|
+
## Installation
|
|
17
|
+
|
|
18
|
+
### Option 1: Install from GitHub
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
# Clone and install locally
|
|
22
|
+
git clone https://github.com/thisnick/openclaw-agentmail ~/.openclaw/extensions/agentmail-listener
|
|
23
|
+
cd ~/.openclaw/extensions/agentmail-listener
|
|
24
|
+
npm install
|
|
25
|
+
|
|
26
|
+
# Restart the gateway
|
|
27
|
+
openclaw gateway restart
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
### Option 2: Load via config path
|
|
31
|
+
|
|
32
|
+
In your OpenClaw config (`~/.openclaw/openclaw.json`):
|
|
33
|
+
|
|
34
|
+
```json
|
|
35
|
+
{
|
|
36
|
+
"plugins": {
|
|
37
|
+
"load": {
|
|
38
|
+
"paths": ["/path/to/openclaw-agentmail"]
|
|
39
|
+
}
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Then run `npm install` in the plugin directory and restart the gateway.
|
|
45
|
+
|
|
46
|
+
## Configuration
|
|
47
|
+
|
|
48
|
+
Add to your OpenClaw config under `plugins.entries.agentmail-listener.config`:
|
|
49
|
+
|
|
50
|
+
```json
|
|
51
|
+
{
|
|
52
|
+
"plugins": {
|
|
53
|
+
"entries": {
|
|
54
|
+
"agentmail-listener": {
|
|
55
|
+
"enabled": true,
|
|
56
|
+
"config": {
|
|
57
|
+
"apiKey": "am_us_your_key_here",
|
|
58
|
+
"inboxId": "yourbot@agentmail.to",
|
|
59
|
+
"eventTypes": ["message.received"],
|
|
60
|
+
"sessionKey": "main"
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
### Config fields
|
|
69
|
+
|
|
70
|
+
| Field | Type | Required | Default | Description |
|
|
71
|
+
|-------|------|----------|---------|-------------|
|
|
72
|
+
| `apiKey` | string | ✅ | — | Your AgentMail API key |
|
|
73
|
+
| `inboxId` | string | ✅ | — | Inbox to subscribe (e.g. `nickbot@agentmail.to`) |
|
|
74
|
+
| `eventTypes` | string[] | — | `["message.received"]` | Event types to subscribe to |
|
|
75
|
+
| `sessionKey` | string | — | `"main"` | Agent session key for routing system events |
|
|
76
|
+
|
|
77
|
+
## System event format
|
|
78
|
+
|
|
79
|
+
When an email arrives, the plugin injects a system event like:
|
|
80
|
+
|
|
81
|
+
```
|
|
82
|
+
📧 New email in nickbot@agentmail.to
|
|
83
|
+
From: sender@example.com
|
|
84
|
+
Subject: Hello there
|
|
85
|
+
Preview: This is the first 200 chars of the email body...
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
The event is keyed with `contextKey: agentmail:<messageId>` to deduplicate repeated events for the same message.
|
|
89
|
+
|
|
90
|
+
## Architecture notes
|
|
91
|
+
|
|
92
|
+
- The plugin uses the `agentmail` npm package's WebSocket client
|
|
93
|
+
- Reconnection uses exponential backoff (1s → 2s → 4s → ... → 60s max) with ±10% jitter
|
|
94
|
+
- Re-subscription happens automatically on each reconnect (WebSocket `open` event)
|
|
95
|
+
- Uses `api.runtime.system.enqueueSystemEvent()` to route events to the agent session
|
|
96
|
+
|
|
97
|
+
## Dependencies
|
|
98
|
+
|
|
99
|
+
- `agentmail` ^0.2.17 — AgentMail TypeScript SDK
|
|
100
|
+
|
|
101
|
+
## License
|
|
102
|
+
|
|
103
|
+
MIT
|