API Documentation

WebSocket

Receive new emails in real time over a persistent WebSocket connection. Instead of polling the inbox endpoint repeatedly, your client opens a single socket and the server pushes a JSON event the moment a new email arrives at any address you have subscribed to.

Endpoint

wss://api.inboxburn.com/ws

A standard WebSocket connection over TLS. No special handshake or authentication header is required.

Subscribe to an inbox

After the connection opens, send the address and the inbox token returned by generate:

{ "action": "subscribe", "address": "[email protected]", "token": "<inbox-token>" }

The server replies with a confirmation event:

{ "type": "subscribed", "address": "[email protected]" }

One subscription per connection. To listen to multiple inboxes, open multiple WebSocket connections.

Receiving new emails

When a new email arrives at the subscribed address, the server pushes a new_email event with metadata:

{ "type": "new_email", "email": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "from_name": "GitHub", "from_address": "[email protected]", "subject": "Verify your email", "received_at": "2026-04-07T15:00:00Z" } }

The push payload contains only summary fields. To get the full HTML/text body and attachments, follow up with GET /api/email/{id}?address={address}.

Authentication & plan limits

  • Opening a WebSocket does not require an API key, but every subscription requires the private inbox token returned by generate.
  • Free, Starter, Pro and Business plan API key holders can all use WebSocket. Sockets do not count toward your monthly REST quota.
  • Idle connections are kept open up to 24 hours by the server timeout. Implement reconnection if you need to listen indefinitely.

Reconnection & reliability

Production clients should handle disconnects gracefully — re-open the socket and re-send the subscribe message. The server does not replay missed messages, so combine WebSocket pushes with periodic GET /api/inbox/{address} polling for guaranteed delivery.

Examples

JavaScript / Browser

const ws = new WebSocket("wss://api.inboxburn.com/ws"); ws.onopen = () => { ws.send(JSON.stringify({ action: "subscribe", address: "[email protected]", token: "<inbox-token>" })); }; ws.onmessage = (event) => { const msg = JSON.parse(event.data); if (msg.type === "subscribed") { console.log("Subscribed to", msg.address); } else if (msg.type === "new_email") { console.log("New email:", msg.email.subject); // Fetch full body via /api/email/{id}?address={address} } }; ws.onerror = (err) => console.error("WS error:", err); ws.onclose = () => console.log("WS closed");

Node.js (ws package)

import WebSocket from "ws"; const ws = new WebSocket("wss://api.inboxburn.com/ws"); ws.on("open", () => { ws.send(JSON.stringify({ action: "subscribe", address: "[email protected]", token: "<inbox-token>" })); }); ws.on("message", (data) => { const msg = JSON.parse(data.toString()); if (msg.type === "new_email") { console.log("New:", msg.email.subject); } }); ws.on("close", () => { console.log("Reconnect logic here"); });

Python (websockets)

import asyncio import json import websockets async def listen(): url = "wss://api.inboxburn.com/ws" async with websockets.connect(url) as ws: await ws.send(json.dumps({ "action": "subscribe", "address": "[email protected]", "token": "<inbox-token>" })) async for raw in ws: msg = json.loads(raw) if msg.get("type") == "new_email": print("New:", msg["email"]["subject"]) asyncio.run(listen())