Import AITURK IDE 1.0.0-beta.1 from Hermes 63279301; preserve MIT license

optional-skills/email/agentmail/references/websockets.md

@@ -0,0 +1,55 @@
+# 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=["agent@agentmail.to"],
+        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": ["agent@agentmail.to"] }
+```
+
+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.