hermes-agent/optional-skills/email/agentmail/references/websockets.md
Haakam Aujla 14320d18df feat(skills): rewrite AgentMail optional skill CLI-first
Replaces the stale MCP-first AgentMail skill with CLI-first guidance:
self-signup + OTP verification, inbox/message/thread/label/attachment
flows, webhook and WebSocket delivery references, and MCP as an
alternative path. Declares AGENTMAIL_API_KEY (optional) so a stored key
reaches the sandboxed terminal while self-signup stays viable without
one.

Salvaged from PR #60811 — kept in optional-skills/ per the March 2026
decision that third-party-API-key skills are not bundled.
2026-08-27 07:09:26 -07:00

55 lines
1.3 KiB
Markdown

# AgentMail WebSockets
Use WebSockets when a local agent process needs realtime inbound mail. After an
event arrives, use the CLI for inbox, send, reply, label, and attachment work.
## Python
The Python example needs the separate AgentMail Python SDK, not the CLI:
```bash
pip install agentmail
```
`AgentMail()` reads `AGENTMAIL_API_KEY` from the environment. If the SDK is
unavailable, use the `Raw` WebSocket below instead.
```python
from agentmail import AgentMail, MessageReceivedEvent, Subscribe
client = AgentMail()
with client.websockets.connect() as socket:
socket.send_subscribe(Subscribe(
inbox_ids=["[email protected]"],
event_types=["message.received"],
))
for event in socket:
if isinstance(event, MessageReceivedEvent):
print(event.message.subject, event.message.from_)
```
## Raw
```text
wss://ws.agentmail.to/v0?api_key=$AGENTMAIL_API_KEY
```
EU region:
```text
wss://ws.agentmail.eu/v0?api_key=$AGENTMAIL_API_KEY
```
Subscribe frame:
```json
{ "type": "subscribe", "event_types": ["message.received"], "inbox_ids": ["[email protected]"] }
```
Omit `inbox_ids` and `pod_ids` for the API key scope.
## Loop Rules
- Dedupe every event by `event_id`.
- Reconnect with backoff and resubscribe after reconnecting.