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 theAuthorization header or token query parameter.
?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
- Your server is already publicly accessible
- You need guaranteed delivery with automatic retries
- You prefer stateless, request-based integration
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.