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.