Endpoints

Bulk validation

On this page

How it works
Quick start
File requirements
Job statuses
Credits
Rate limits
Output
Single, batch or bulk?
Related

Upload a CSV file, let SimpleCold work through it in the background, then download a result file that keeps every original column and adds the verification fields at the end. Use it for whole lists and CRM exports.

How it works

Upload a CSV with POST /api-validation/bulk. Credits for every unique address are reserved and the job starts straight away, with status IN PROGRESS.
Poll the status with GET /api-validation/bulk/:id/status until it is COMPLETED. The response tells you when progress will next change, so you know when to ask again.
Download the results with GET /api-validation/bulk/:id/download-result, as CSV or JSON.

Your code finds out a job is done either by polling its status, or by subscribing to the bulk.finished webhook.

Quick start

1 · Upload

curl "https://simplecold.com/api/v1/api-validation/bulk" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected];type=text/csv"

2 · Status

curl "https://simplecold.com/api/v1/api-validation/bulk/JOB_ID/status" \
  -H "Authorization: Bearer YOUR_API_KEY"

3 · Download

curl -o results.csv \
  "https://simplecold.com/api/v1/api-validation/bulk/JOB_ID/download-result?output=csv&verifiedOnly=false" \
  -H "Authorization: Bearer YOUR_API_KEY"

File requirements

Format: CSV, sent as multipart/form-data in a field named file with content type text/csv.
Size: up to 50 MB.
Header row: the first row must be a header row.
Email column: one column must be named email, e-mail, email address, emailaddress, emails or mail (case and surrounding spaces are ignored). Otherwise the upload fails with Email column not found in the file.
Delimiters: commas, semicolons and tabs all work.
Rows: rows with an empty email cell are skipped. Duplicate addresses are removed, so each address is checked and charged once.

leads.csv

name,email,company
Jane Doe,[email protected],Acme Corp
Sam Lee,[email protected],Tech Inc

Job statuses

Status	Meaning
`IN PROGRESS`	The job is running. Note the space: it is `IN PROGRESS`, not `IN_PROGRESS`.
`COMPLETED`	Every address has a result. Download the file.
`CANCELING`	A cancel was requested (from the dashboard) and is finishing.
`CANCELED`	The job was canceled. Rows that were finished have results; the rest show the reason code `no_response` (category `risky`) and their credits are released.
`FAILED`	The job stopped. Its reserved credits are released, and you can retry it from the dashboard.
`QUEUE`	The job is waiting to start. Only jobs queued from the dashboard use this; API uploads start immediately.

Credits

Credits for every unique address in the file are reserved at upload. If your balance is too low, the upload fails with 400 Insufficient credits. (or Please buy credits.) and no job is created. If a job fails, the reserved credits are released. If you cancel a job, credits for rows that never got a result are released.

Rate limits

Per API key: 10 uploads per minute, 120 status requests per minute and 30 downloads per minute. Each has its own budget, so polling status never uses up your uploads. Still poll at the time the status response suggests (nextUpdateAt): progress only moves then. See Rate limits.

Output

The result file keeps your original columns first, with their exact header text, and adds these columns at the end:

Result, Reason, Reason code, Suggestion, Retry later, Domain, Mail server country, Website country, Website language

Download with output=json to get the same rows as an array of objects. Download the results explains every column and key.

Single, batch or bulk?

	Single	Batch	Bulk
Addresses per call	1	Up to 50	A CSV up to 50 MB
Response	Within about 12 s	Within about 25 s	Background job, polled
Rate limit	100 / min	10 / min	10 uploads / min (status 120 / min, download 30 / min)
Test addresses free	Yes	Yes	No
Best for	Sign-up and lead forms	Small lists from a script	Whole lists and CRM exports