Skip to main content

Minimal example

Connect, subscribe, and log incoming events.
const WebSocket = require("ws");

const ws = new WebSocket("wss://api.openmail.sh/v1/ws", {
  headers: { Authorization: `Bearer ${process.env.OPENMAIL_API_KEY}` },
});

ws.on("open", () => {
  ws.send(JSON.stringify({ type: "subscribe" }));
});

ws.on("message", (data) => {
  const event = JSON.parse(data);

  if (event.type === "subscribed") {
    console.log("Subscribed — inboxes:", event.inbox_ids, "events:", event.event_types);
  } else if (event.event === "message.received") {
    console.log(`From: ${event.message.from}`);
    console.log(`Subject: ${event.message.subject}`);
    console.log(`Body: ${event.message.body_text}`);
  }
});

Production example

Adds reconnection with exponential backoff and last_event_id replay to avoid losing events during disconnects.
const WebSocket = require("ws");

const OPENMAIL_API_KEY = process.env.OPENMAIL_API_KEY;
let lastEventId = null;
let retries = 0;

function connect() {
  const ws = new WebSocket("wss://api.openmail.sh/v1/ws", {
    headers: { Authorization: `Bearer ${OPENMAIL_API_KEY}` },
  });

  ws.on("open", () => {
    console.log("Connected to OpenMail");
    const sub = { type: "subscribe" };
    if (lastEventId) sub.last_event_id = lastEventId;
    ws.send(JSON.stringify(sub));
    retries = 0;
  });

  ws.on("message", (data) => {
    const event = JSON.parse(data);

    if (event.type === "subscribed") {
      console.log("Subscribed — inboxes:", event.inbox_ids, "events:", event.event_types);
      return;
    }

    if (event.event === "message.received") {
      lastEventId = event.event_id;
      console.log(`New email from: ${event.message.from}`);
      console.log(`Subject: ${event.message.subject}`);

      const container = getContainerByUserId(event.external_id);
      container.deliverEmail({
        threadId: event.thread_id,
        message: event.message,
      });
    }
  });

  ws.on("close", (code) => {
    console.log(`Disconnected (${code}), reconnecting...`);
    setTimeout(connect, Math.min(1000 * Math.pow(2, retries++), 30000));
  });

  ws.on("error", (err) => {
    console.error("WebSocket error:", err.message);
  });
}

connect();