Realtime SSE

Guides

Reference

End Points Overview

Single Email Validation

Bulk Email Validation

Tutorials

Realtime SSE

Credits & Billing

Error & Status Codes

Search Docs…

The Realtime SSE endpoint allows you to receive live job progress updates as your bulk validation job is being processed.
Instead of polling the /status endpoint repeatedly, you can subscribe to a streaming connection and receive updates the moment they occur.

This is ideal for dashboards, progress bars, admin tools, and long-running list validations.

1. Endpoint

GET /api/v1/jobs/{job_id}/stream

This endpoint opens a Server-Sent Events (SSE) stream.
The connection remains open until:

The job is completed
The job fails
The client closes the stream
A network interruption occurs

Authentication (Required)

Authorization: Bearer YOUR_API_KEY

2. How SSE Works

When you connect to the stream, the server sends events such as:

status → job progress update
error → processing issue or job failure

Example event:

event: status
data: {"progress_percentage":75,"processed_count":750,"total_emails":1000}

3. JavaScript Browser Example (EventSource)

const jobId = "550e8400-e29b-41d4-a716-446655440000";

const eventSource = new EventSource(
  `https://rapid-email-verifier.fly.dev/api/v1/jobs/${jobId}/stream`,
  { withCredentials: false }
);

eventSource.addEventListener("status", (event) => {
  const data = JSON.parse(event.data);
  console.log("Progress:", data.progress_percentage + "%");
  console.log("Processed:", data.processed_count + "/" + data.total_emails);

  if (data.status === "completed" || data.status === "failed") {
    eventSource.close();
  }
});

eventSource.addEventListener("error", (event) => {
  console.error("SSE error:", event);
  eventSource.close();
});

⚠️ Note:
Browsers do not support custom headers in EventSource.
If your API requires Authorization headers, you must:

Use a backend proxy
OR
Switch to Axios / custom SSE clients in Node.js

4. Node.js Server Example (eventsource package)

const EventSource = require("eventsource");

const url = "https://rapid-email-verifier.fly.dev/api/v1/jobs/550e8400-e29b.../stream";

const eventSource = new EventSource(url, {
  headers: { "Authorization": "Bearer YOUR_API_KEY" }
});

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(`Progress: ${data.progress_percentage}%`);
};

eventSource.onerror = (err) => {
  console.error("SSE Error:", err);
  eventSource.close();
};

5. Event Types

status

Emitted when job progress updates.

Example:

event: status
data: {
  "job_id": "550e8400...",
  "status": "processing",
  "total_emails": 1000,
  "processed_count": 750,
  "progress_percentage": 75
}

error

Emitted when the job encounters an issue.

Example:

event: error
data: {"message":"Job failed due to invalid file format"}

6. Frequency & Behavior

Updates are sent every 1 second during processing
The connection automatically closes when:
- Status = completed
- Status = failed
Clients should implement reconnection logic if needed

7. Example of Full SSE Event Series

event: status
data: {"progress_percentage":5}

event: status
data: {"progress_percentage":38}

event: status
data: {"progress_percentage":87}

event: status
data: {"progress_percentage":100}

event: status
data: {"status":"completed"}

At the end of the job, you can:

Fetch paginated results using /results
Download the file using /download

8. Common SSE Errors

401 Unauthorized

{
  "success": false,
  "error": { "code": "UNAUTHORIZED", "message": "Invalid API key" }
}

404 Job Not Found

{
  "success": false,
  "error": { "code": "JOB_NOT_FOUND", "message": "Job not found" }
}

Job Failure Event

event: error
data: {"message":"File format invalid"}

9. Best Practices

Use SSE instead of polling for better efficiency
Close the connection after job completes
Show progress bars using processed_count & total_emails
For large dashboards, avoid opening too many SSE connections
Use Node.js if you need custom headers in SSE
Always fallback to /status if SSE fails

‹ Credits & Billing

Bulk Email Validation ›

Search Docs…