Open a WebSocket connection

Upgrade this GET to a WebSocket. After the handshake, the server sends a connected frame and the client sends a subscribe frame to start receiving events.

This protocol is wire-compatible with agentmail.to's WebSocket API — workspace_ids also accepts pod_ids as an alias.

Client → server frames

{ "type": "subscribe",
  "event_types": ["message.received", "message.sent"],
  "inbox_ids":    ["..."],
  "workspace_ids": ["..."] }

Server → client frames

{ "type": "connected", "inboxId": "...", "email": "..." }
{ "type": "subscribed", "event_types": [...], "inbox_ids": [...], "workspace_ids": [...] }
{ "type": "event",
  "event_type": "message.received",
  "event_id":   "evt_...",
  "message":    { "inbox_id": "...", "thread_id": "...", "from": "...", "to": ["..."], "subject": "...", "plain_body": "...", "html_body": "...", "timestamp": "..." },
  "thread":     { "thread_id": "...", "subject": "..." } }
{ "type": "ping" }
{ "type": "error", "message": "..." }

Use ?api_key=<key> as a query parameter when your client (e.g. browser new WebSocket) can't set the X-API-Key header.