HomeDocsWebSocket Events

WebSocket Events

Real-time email delivery via persistent WebSocket connections.

Connecting

Open a WebSocket connection to receive real-time email notifications. Pass your mailbox ID and session token as query parameters.

WebSocket URL

wss://minutemail.xyz/ws?mailboxId={id}&token={sessionToken}

javascript
const ws = new WebSocket(
  "wss://minutemail.xyz/ws?mailboxId=abc123&token=tok_abc123..."
);

ws.onopen = () => {
  console.log("Connected to mailbox stream");
};

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log("Event:", data.type, data);
};

ws.onclose = (event) => {
  console.log("Disconnected:", event.code, event.reason);
};

Event Types

All messages are JSON objects with a type field identifying the event.

new_emailFired when a new email arrives
json
{
  "type": "new_email",
  "email": {
    "id": "email_001",
    "from": "[email protected]",
    "fromName": "Example App",
    "subject": "Verify your email",
    "preview": "Click the link below to verify...",
    "receivedAt": 1711738900000,
    "read": false
  }
}
mailbox_expiredFired when the mailbox TTL reaches zero
json
{
  "type": "mailbox_expired",
  "mailboxId": "abc123def456"
}

The connection will be closed shortly after this event.

pingpongKeepalive heartbeat
json
{ "type": "ping" }

Respond with {"type":"pong"} within 30 seconds.

Keepalive

The server sends a ping every 25 seconds. If no pong response is received within 30 seconds, the connection will be dropped. Implement automatic replies:

javascript
ws.onmessage = (event) => {
  const data = JSON.parse(event.data);

  if (data.type === "ping") {
    ws.send(JSON.stringify({ type: "pong" }));
    return;
  }

  // Handle other events
  if (data.type === "new_email") {
    console.log("New email from:", data.email.from);
  }
};

Reconnection Strategy

Connections can drop due to network issues or server restarts. Implement exponential backoff for reliable reconnection.

javascript
function connectMailbox(mailboxId, token) {
  let retryDelay = 2000; // Start at 2s
  const maxDelay = 30000; // Cap at 30s

  function connect() {
    const ws = new WebSocket(
      `wss://minutemail.xyz/ws?mailboxId=${mailboxId}&token=${token}`
    );

    ws.onopen = () => {
      retryDelay = 2000; // Reset on success
      console.log("Connected");
    };

    ws.onclose = (event) => {
      if (event.code === 1008) {
        // Mailbox expired — don't reconnect
        console.log("Mailbox expired");
        return;
      }
      console.log(`Reconnecting in ${retryDelay / 1000}s...`);
      setTimeout(connect, retryDelay);
      retryDelay = Math.min(retryDelay * 2, maxDelay);
    };

    ws.onmessage = (event) => {
      const data = JSON.parse(event.data);
      if (data.type === "ping") {
        ws.send(JSON.stringify({ type: "pong" }));
      }
    };

    return ws;
  }

  return connect();
}

Tip

Close code 1008 indicates the mailbox has expired. Don't attempt to reconnect after receiving it.

PreviousAPI ReferenceNext FAQ