This script takes a CSV with an email column, submits it as a single bulk job, polls for completion, and writes output.csv with one row per unique address plus classification, sub_status, and confidence_score columns.

Requirements

pip install requests

The script

import csv
import os
import sys
import time
import requests

API_KEY = os.environ["ROCKETVERIFIER_API_KEY"]  # rv_live_... or rv_test_...
BASE_URL = "https://api.rocketverifier.com"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def read_emails(path: str) -> list[str]:
    with open(path, newline="") as f:
        reader = csv.DictReader(f)
        return [row["email"].strip() for row in reader if row.get("email", "").strip()]


def create_bulk_job(emails: list[str], name: str) -> str:
    # Up to 100,000 unique emails per job; duplicates are removed (and not charged) server-side.
    resp = requests.post(
        f"{BASE_URL}/v1/verify/bulk",
        headers=HEADERS,
        json={"emails": emails, "name": name},
        timeout=60,
    )
    resp.raise_for_status()
    job = resp.json()
    print(f"Job {job['job_id']}: {job['total_emails']} unique emails, {job['credits_to_use']} credits reserved")
    return job["job_id"]


def poll_job(job_id: str, interval_seconds: int = 5) -> None:
    while True:
        resp = requests.get(f"{BASE_URL}/v1/jobs/{job_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        job = resp.json()
        print(f"Job {job_id}: {job['status']} ({job['progress_percent']:.0f}%)")
        if job["status"] == "completed":
            return
        if job["status"] in ("failed", "cancelled"):
            raise RuntimeError(f"Bulk job {job_id} ended with status {job['status']}")
        time.sleep(interval_seconds)


def fetch_results(job_id: str) -> list[dict]:
    results, page = [], 1
    while True:
        resp = requests.get(
            f"{BASE_URL}/v1/jobs/{job_id}/results",
            headers=HEADERS,
            params={"page": page, "limit": 1000},  # max 1,000 per page
            timeout=60,
        )
        resp.raise_for_status()
        body = resp.json()
        results.extend(body["results"])
        if not body["has_more"]:
            return results
        page += 1


def write_output(results: list[dict], path: str = "output.csv") -> None:
    columns = ["email", "classification", "sub_status", "confidence_score",
               "is_valid", "is_disposable", "is_catch_all", "verified_at"]
    with open(path, "w", newline="") as f:
        writer = csv.DictWriter(f, fieldnames=columns, extrasaction="ignore")
        writer.writeheader()
        writer.writerows(results)
    print(f"Wrote {len(results)} rows to {path}")


def main():
    input_path = sys.argv[1] if len(sys.argv) > 1 else "emails.csv"
    emails = read_emails(input_path)
    print(f"Submitting {len(emails)} emails...")
    job_id = create_bulk_job(emails, name=os.path.basename(input_path))
    poll_job(job_id)
    results = fetch_results(job_id)
    write_output(results)


if __name__ == "__main__":
    main()

Bulk-job rows use the classification field (valid, invalid, risky, catch_all, disposable, unknown) plus sub_status for the precise reason (for example mailbox_not_found, greylisted, role_based). is_valid, is_disposable and is_catch_all are real booleans here. Emails that finish as unknown are refunded automatically when the job completes.

If you’d rather not page through results, GET /v1/jobs/{job_id}/download?format=csv returns the whole file in one response once the job is completed (columns email, classification, is_valid, is_disposable, is_catch_all, is_role_based, confidence_score, sub_status, verified_at).

Running it against the sandbox first

export ROCKETVERIFIER_API_KEY=rv_test_your_sandbox_key
python3 verify_csv.py emails.csv

Point emails.csv at a file of @sandbox.rocketverifier.com addresses (for example deliverable@, undeliverable@, risky@, unknown@) to see the full flow (submit, poll, fetch results, write the CSV) without spending real credits, then swap in a live key and real data once you’ve confirmed the output looks right.

Error handling notes

requests.raise_for_status() will throw on any non-2xx response, including a 401 for an invalid API key, 402 for insufficient credits, or 400 too_many_emails for a file over 100,000 unique addresses. Every error body has the shape {"error": {"code": ..., "message": ..., "details": ...}}, so wrap the create_bulk_job call in a try/except requests.HTTPError block in production and inspect resp.json()["error"]["code"] before retrying. On 429, wait for the number of seconds in the Retry-After header.

To get notified instead of polling, register a webhook for job.completed once (POST /v1/webhooks) and verify its X-RocketVerifier-Signature header with verify_webhook_signature from the rocketverifier package.