Skip to main content
WebSockets provide a persistent connection to OpenMail for receiving email events in real-time. Unlike webhooks, WebSockets don’t require a public URL or external tools like ngrok.

​
Why use WebSockets?

FeatureWebhookWebSocket
SetupRequires public URL + ngrokNo external tools needed
ConnectionHTTP request per eventPersistent connection
InitiationOpenMail connects to youYou connect to OpenMail
FirewallMust expose portOutbound only
LatencyHTTP round-tripInstant streaming
WebSockets are the recommended delivery method for agent platforms. Agents are long-running processes that benefit from a persistent event stream rather than a callback endpoint.

​
Connecting

Authenticate with your API key via the Authorization header or token query parameter. 
const WebSocket = require("ws");

const ws = new WebSocket("wss://api.openmail.sh/v1/ws", {
  headers: { Authorization: `Bearer ${process.env.OPENMAIL_API_KEY}` },
});
The ?token= query parameter is useful for browser clients and CLI tools that can’t set custom headers on WebSocket connections.

​
Delivery semantics

When a customer has both an active WebSocket connection and a webhook URL configured, OpenMail prefers the WebSocket. If the WebSocket is down, events fall back to the webhook with the same retry policy.
ScenarioDelivery method
WebSocket connected + subscribedWebSocket (instant)
WebSocket disconnected, webhook URL setWebhook (with retries)
NeitherEvent stored, marked as failed
Events use the same payload structure as webhooks.

​
Comparison with webhooks

Use WebSockets when:
  • Your agent runs locally or behind a firewall
  • You want instant delivery with no round-trip latency
  • You don’t want to manage a public HTTPS endpoint
Use webhooks when:
  • Your server is already publicly accessible
  • You need guaranteed delivery with automatic retries
  • You prefer stateless, request-based integration
Both deliver the same event payload. You can switch between them without changing your event handling logic.

Quickstart

Connect and receive events in under 10 lines.

Protocol reference

Message types, subscribe options, event replay, connection management.

Webhook events

Event payload structure (shared with WebSocket).

Webhook setup

Configure webhook endpoints with signature verification.