# Open a WebSocket connection

**`GET https://myagentmail.com/v1/ws`**

Group: WebSocket
Operation ID: `openWebSocket`

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

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

### Server → client frames

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


## Responses

### 101 — Switching protocols

### 401 — Missing or invalid API key

```json
{
  "error": "string",
  "code": "VALIDATION_ERROR"
}
```

## Code samples

### TypeScript

```typescript
import { MyAgentMail } from "myagentmail";

const client = new MyAgentMail({ apiKey: process.env.MYAGENTMAIL_API_KEY! });

// GET /v1/ws
const result = await client.request("get", "/v1/ws");
```

### curl

```bash
curl -X GET 'https://myagentmail.com/v1/ws' \
  -H 'X-API-Key: $MYAGENTMAIL_API_KEY'
```

### Python

```python
import os, requests

r = requests.get(
    "https://myagentmail.com/v1/ws",
    headers={"X-API-Key": os.environ["MYAGENTMAIL_API_KEY"]},
)
r.raise_for_status()
print(r.json())
```