Stream validation events via Server-Sent Events

GET /api/v1/events/stream

API key required Base https://api.emailvalidator.ai

Connect to a Server-Sent Events (SSE) stream that delivers validation results in real time. Each event is a JSON-encoded WebhookEnvelope. The stream sends a : heartbeat comment periodically to keep the connection alive.

Population — the stream carries exactly what the list endpoints return for the same key: the key's ACCOUNT (every team member's submissions, not only the key holder's), API-submitted work only (dashboard validations are the dashboard's), and the key's MODE (ev_test_ keys see sandbox events, live keys see live ones). If a verification does not appear in GET /api/v1/verify for a key, it will not appear on that key's stream either — one rule for both.

Reconnection — on disconnect reconnect with Last-Event-ID set to the last received event ID, or ?since=<ISO-8601> to replay events from a specific time. The replay applies the same population rule as the live feed.

Note: this endpoint is not rate-limited (reconnect loops would exhaust a per-minute budget).

Authentication — use the ?api_key= query parameter when a browser EventSource is used (it cannot set custom headers).

On this page

Parameters
Responses
Error responses

Parameters

query · parameters

Parameter	Type	Description
since	string	ISO-8601 timestamp or tick count. Returns events after this point. example: 2025-06-10T14:00:00Z

header · parameters

Parameter	Type	Description
Last-Event-ID	string	SSE reconnect protocol — tick count of the last received event.

Responses

200

SSE stream established. Events are delivered as text/event-stream. · text/event-stream

string

Each event follows the SSE wire format:

id: <ticks>
event: verify.completed
data: <WebhookEnvelope JSON>

401

Missing or invalid API key. · application/json

403

The API key authenticated but is not scoped for this endpoint (code: insufficient_scope). It is a 403 rather than a 401 on purpose — the credential is valid, so retrying with it can never help; a key holding the read scope is needed. · application/json

500

Unexpected server error. The body carries code internal_error plus a request_id to quote in a support request, and never any exception detail. Raised only before the SSE stream has started — once events are flowing the connection simply ends. · application/json

Error responses

401 403 500 · ApiProblem · object

Standard error response shape used by all error status codes.

Field	Type	Description
status required	integer	HTTP status code mirrored in the body. example: 400
code required	string	Stable, machine-readable error code. Branch your code on this — never on the `error` text, which is prose and may be reworded at any time. example: invalid_email
error required	string	Human-readable error message. example: Invalid email format.
param	string	The request field the failure is attributable to. Omitted when the failure is not about one specific field. example: email
details	array of string · null	Optional per-field validation messages. Null when not applicable. example: ["email: required"]
doc_url	string	Link to the documentation for this error code. example: https://emailvalidator.ai/docs/get-started/errors
request_id	string	Correlation id for this request. Quote it in a support request — it is how a single call is found in the server logs. example: 0HNCV1TQ3PLRK:00000003