aiturk-hermes-ide/optional-skills/email/agentmail/references/websockets.md

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:

pip install agentmail

AgentMail() reads AGENTMAIL_API_KEY from the environment. If the SDK is unavailable, use the Raw WebSocket below instead.

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

wss://ws.agentmail.to/v0?api_key=$AGENTMAIL_API_KEY

EU region:

wss://ws.agentmail.eu/v0?api_key=$AGENTMAIL_API_KEY

Subscribe frame:

{ "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.