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?

WebSockets are the recommended delivery method for agents. 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.
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. Events use the same payload structure as webhooks. Emails that are blocked by sender rules or filtered out by allowlist mode do not generate events.

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.