Bulk Email Validation

Guides

Reference

End Points Overview

Single Email Validation

Tutorials

Realtime SSE

Credits & Billing

Error & Status Codes

Search Docs…

Bulk Validation allows you to process large lists of email addresses asynchronously.
You can submit email arrays directly or upload CSV/JSON/TXT files up to 10MB.
Once a job is created, you can poll for status, stream real-time progress, and download the final results.

This workflow is ideal for CRM cleaning, marketing list hygiene, lead enrichment, or onboarding datasets.

1. Supported Workflow

Bulk processing follows a simple 4-step pipeline:

1. Create a Bulk Job  (array or file upload)
2. Check Job Status  (polling or SSE)
3. Fetch Results     (paginated API)
4. Download Results  (CSV or JSON file)

2. Create a Bulk Job (Email Array)

POST /api/v1/jobs

Request Body

{
  "emails": [
    "user1@example.com",
    "user2@example.com",
    "user3@example.com"
  ],
  "source_type": "api"
}

Limits

Min: 2 emails
Max: 1,000 emails
For single email validation → use /api/validate

Example CURL

curl -X POST https://rapid-email-verifier.fly.dev/api/v1/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails":["user1@example.com","user2@example.com"]}'

Sucess Response(202 Accepted)

{
  "success": true,
  "data": {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "pending",
    "total_emails": 3,
    "status_url": "/api/v1/jobs/550e8400.../status",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

3. Create a Bulk Job (File Upload)

POST /api/v1/jobs/upload

Upload a .csv, .json, or .txt file containing email addresses.

CURL

curl -X POST https://rapid-email-verifier.fly.dev/api/v1/jobs/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@emails.csv"

Supported File types

Type	Format
CSV	Must contain `email` column
JSON	Array of String objects
TXT	One Email per line

CSV Example

email
user1@example.com
user2@example.com

JSON Example

[
  "user1@example.com",
  "user2@example.com"
]

Success Response (202 Accepted)

{
  "success": true,
  "data": {
    "job_id": "550e8400-e29b...",
    "status": "pending",
    "total_emails": 1000,
    "file_name": "emails.csv",
    "file_size": 45678,
    "status_url": "/api/v1/jobs/550e8400.../status"
  }
}

File Limits

Max file size: 10MB
Max emails per job: 1,000

Possible Errors

400 — Invalid Format

{
  "success": false,
  "error": {
    "code": "INVALID_FILE_FORMAT",
    "message": "File must be CSV, JSON, or TXT format"
  }
}

413 — File Too Large

{
  "success": false,
  "error": {
    "code": "FILE_TOO_LARGE",
    "message": "File size exceeds 10MB limit"
  }
}

4. Check Job Status

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

Fetch real-time job progress and stats

curl https://rapid-email-verifier.fly.dev/api/v1/jobs/550e8400.../status \
  -H "Authorization: Bearer YOUR_API_KEY"

Sucess Response

{
  "success": true,
  "data": {
    "job_id": "550e84...",
    "status": "processing",
    "total_emails": 1000,
    "processed_count": 750,
    "valid_count": 650,
    "invalid_count": 100,
    "progress_percentage": 75,
    "created_at": "2025-01-15T10:30:00Z",
    "started_at": "2025-01-15T10:30:05Z",
    "completed_at": null
  }
}

Status Values

Status	Meaning
queued	Waiting in queue
processing	Validation in progress
completed	Job finished successfully
failed	Job encountered error
Cancelled	Job was manually cancelled

Possible Errors

404 — Job Not Found

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

5. Fetch Results (Paginated API)

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

Get structured JSON results for each validated email.

Param	Default	Max	Description
`page`	1	—	Page number
`limit`	100	1000	Rows per page
`format`	json	csv	Output format

Example

curl "https://rapid-email-verifier.fly.dev/api/v1/jobs/550e8400.../results?page=1&limit=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

{
  "success": true,
  "data": {
    "job_id": "550e84...",
    "job_status": "completed",
    "total_count": 1000,
    "results": [
      {
        "email": "user1@example.com",
        "status": "VALID",
        "score": 95,
        "validations": {
          "syntax": true,
          "domain_exists": true,
          "mx_records": true,
          "mailbox_exists": true
        },
        "is_spamtrap": false,
        "is_abuse": false,
        "is_toxic": false,
        "is_global_suppression": false
      }
    ],
    "offset": 0,
    "limit": 100,
    "has_more": true
  }
}

6. Download Full Results File

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

Download final results as a CSV or JSON file.

Query Params

Name	Default	Options
`format`	csv	csv, json

Example

curl "https://rapid-email-verifier.fly.dev/api/v1/jobs/550e84.../download?format=csv" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o results.csv

CSV Output Example

email,status,score,is_disposable,is_role_based,is_spamtrap,is_abuse,is_toxic,domain,mx_records
user1@example.com,VALID,95,false,false,false,false,false,example.com,"[""mail.example.com""]"

Expiration Policy

Results available for 7 days
After expiration → file permanently removed

Error (410 Gone)

{
  "success": false,
  "error": {
    "code": "RESULTS_EXPIRED",
    "message": "Job results have expired and been deleted"
  }
}

7. Best Practices for Bulk Processing

Use CSV for large lists (fastest parsing)
Use SSE for live job tracking
Split jobs into <1,000 emails for maximum performance
Validate list quality before marketing sends
Discard spamtrap, abuse, toxic & suppression emails
Cache validated results to avoid duplicate charges

‹ Realtime SSE

Single Email Validation ›

Search Docs…