WebSockets

Connect to /v0/websocket, then send a subscribe message. Send the key in the Authorization: Bearer header; ?api_key= also works for browsers, which cannot set headers, but URLs are logged by proxies, so avoid it elsewhere.

import { EmailingAgentsClient } from "emailingagents-sdk";

const client = new EmailingAgentsClient({ apiKey: process.env.API_KEY!, baseUrl: process.env.BASE_URL! });
const socket = client.websockets.connect(
  { inbox_ids: ["support-agent@example.com"], event_types: ["message.received"] },
  { onEvent: (e) => console.log(e.event_type, e.event_id) },
);
// later: socket.close();

On the wire, after the socket opens:

{ "type": "subscribe", "inbox_ids": ["inbox_..."], "pod_ids": [], "event_types": ["message.received"] }

The server replies { "type": "subscribed", "inbox_ids": [...], "pod_ids": [...], "event_types": [...] }, then pushes { "type": "event", ... } frames with the same shape as webhook bodies. Inbox ids can be addresses. Unknown inboxes are ignored. Omitting event_types selects the default set. Invalid messages get { "type": "error", "message": "..." }.

Events are delivered only while connected; there is no replay. Reconnect and call GET /v0/events?after=... to catch up. Use webhooks when you need retries.