Skip to content
Docs Bulk uploads

Bulk uploads

CSV and Excel jobs up to 50,000 rows: upload, poll, filter and export results.

Bulk jobs verify a whole file asynchronously. The flow: upload, poll status, fetch results.

1. Upload

upload.sh
curl -X POST "https://api.kavik.email/api/v1/verify/async/upload" \
  -H "X-API-Key: eva_your_key" \
  -F "file=@list.csv"

CSV and Excel (.xlsx) uploads are accepted. The address column is found automatically: a header named email, email_address or e-mail wins, otherwise the column holding the most addresses is used. Row caps by plan: Free 300 (the one-time allowance from signup) plus any credits held, up to 10,000; Starter 10,000, Pro 20,000, Business 50,000, Scale 300K 100,000, Scale 500K 150,000, Enterprise 1,000,000. Uploads over the API need a plan or a credit pack, and a file above the cap is refused. A dashboard upload from a free account with no credits checks the first addresses instead, up to what is left of its 300 free checks. A per-job webhook_url can be passed at upload to be called when the job completes.

A test key runs test jobs from the sandbox: up to 1,000 rows of test addresses, 3 running and 20 an hour, deleted after 24 hours. A job object, and each result row in JSON, carries livemode.

2. Poll status

status.sh
curl "https://api.kavik.email/api/v1/verify/async/{id}" \
  -H "X-API-Key: eva_your_key"

A job that sits at 100% while still processing is running its greylist retry pass; that is normal, and the retries happen inside the job.

3. Fetch results

result.sh
curl "https://api.kavik.email/api/v1/verify/async/{id}/result" \
  -H "X-API-Key: eva_your_key"

The endpoint returns the full result set for the job. Two optional parameters shape it: ?risk=safe,risky,catchall,invalid,unknown filters rows by verdict, and ?format=csv downloads the set as CSV instead of JSON. Exports to CSV or Excel are also available from the dashboard. Unknowns are never billed and can be re-run with POST /api/v1/verify/async/{id}/rerun-unknowns after a 30-minute cooldown (test jobs have no wait). CSV and Excel downloads do not carry livemode.

Free plan results

While an account is on the Free plan without credits, its jobs return results_locked: true. GET /api/v1/verify/async/{id}/summary returns the count for each verdict and up to 10 sample rows, and /result answers 403 RESULTS_LOCKED. Any plan or credit pack unlocks the full results, including for uploads run before buying.

Job control

pause, resume, and cancel endpoints exist at /api/v1/verify/async/{id}/pause (and .../resume, .../cancel).