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.