Bulk jobs API

# A CSV file with a header row; the email column is found automatically.
curl https://api.email-validation.org/v1/bulk \
  -H "Authorization: Bearer $EV_API_KEY" \
  -H "Content-Type: text/csv" \
  --data-binary @customers.csv

# Or a JSON list, without starting it yet:
curl "https://api.email-validation.org/v1/bulk?start=false" \
  -H "Authorization: Bearer $EV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"emails": ["accepted@sandbox.email-validation.org", "catch_all@sandbox.email-validation.org"]}'

import { readFile } from 'node:fs/promises';

const csv = await readFile('customers.csv');
const res = await fetch('https://api.email-validation.org/v1/bulk?column=email&has_header=true', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.EV_API_KEY}`,
    'Content-Type': 'text/csv',
  },
  body: csv,
});
const job = await res.json();
if (!res.ok) throw new Error(`${job.error.code}: ${job.error.message}`);
console.log(job.id, job.status);

import os

import requests

with open("customers.csv", "rb") as f:
    resp = requests.post(
        "https://api.email-validation.org/v1/bulk",
        params={"column": "email", "has_header": "true"},
        headers={"Authorization": f"Bearer {os.environ['EV_API_KEY']}", "Content-Type": "text/csv"},
        data=f.read(),
        timeout=120,
    )
job = resp.json()
if not resp.ok:
    raise RuntimeError(f"{job['error']['code']}: {job['error']['message']}")
print(job["id"], job["status"])

JOB=job_3Fv8QpL2xM7nC1rT9kW4yB

# Progress and counts
curl https://api.email-validation.org/v1/bulk/$JOB -H "Authorization: Bearer $EV_API_KEY"

# Start a job that is waiting in "ready"
curl -X POST https://api.email-validation.org/v1/bulk/$JOB/start -H "Authorization: Bearer $EV_API_KEY"

# Download only deliverable and risky rows, with the original columns
curl -o results.csv "https://api.email-validation.org/v1/bulk/$JOB/results?filter=deliverable,risky" \
  -H "Authorization: Bearer $EV_API_KEY"

# Cancel (unused credits are returned)
curl -X DELETE https://api.email-validation.org/v1/bulk/$JOB -H "Authorization: Bearer $EV_API_KEY"

const headers = { Authorization: `Bearer ${process.env.EV_API_KEY}` };
const done = new Set(['completed', 'failed', 'cancelled', 'expired']);

async function waitForJob(id) {
  for (;;) {
    const res = await fetch(`https://api.email-validation.org/v1/bulk/${id}`, { headers });
    const job = await res.json();
    if (!res.ok) throw new Error(`${job.error.code}: ${job.error.message}`);
    if (done.has(job.status)) return job;
    console.log(`${job.processed}/${job.unique_emails ?? '?'} done`);
    await new Promise((resolve) => setTimeout(resolve, 5000));
  }
}

const job = await waitForJob('job_3Fv8QpL2xM7nC1rT9kW4yB');
if (job.status === 'completed') {
  const res = await fetch(`https://api.email-validation.org/v1/bulk/${job.id}/results?filter=deliverable`, { headers });
  console.log(await res.text());
}

import os
import time

import requests

API = "https://api.email-validation.org"
HEADERS = {"Authorization": f"Bearer {os.environ['EV_API_KEY']}"}
DONE = {"completed", "failed", "cancelled", "expired"}


def wait_for_job(job_id: str) -> dict:
    while True:
        job = requests.get(f"{API}/v1/bulk/{job_id}", headers=HEADERS, timeout=10).json()
        if job["status"] in DONE:
            return job
        print(job["processed"], "of", job["unique_emails"], "done")
        time.sleep(5)


job = wait_for_job("job_3Fv8QpL2xM7nC1rT9kW4yB")
if job["status"] == "completed":
    with requests.get(
        f"{API}/v1/bulk/{job['id']}/results", params={"filter": "all"}, headers=HEADERS, stream=True, timeout=60
    ) as r:
        r.raise_for_status()
        with open("results.csv", "wb") as f:
            for chunk in r.iter_content(chunk_size=1 << 20):
                f.write(chunk)