API reference

Bulk jobs

Verify a whole list in the background. Upload JSON, a CSV file or plain text, and download the results in the same order.

Create a job

POST/v1/jobs

Send the list in one of three ways:

application/json with {"emails": [...]}
multipart/form-data with a file field holding a CSV
text/csv or text/plain with one address per line

For CSVs, a column called something like “Email”, “E-mail Address” or “Correo” is found automatically, and other columns are ignored. Pass column to choose one by its header.

Parameter	Description
`name`	A label for the job, shown in the dashboard.
`webhook_url`	Called when the job finishes. See webhooks.
`column`	CSV header of the email column, if it can't be detected.

# Upload a CSV; the email column is found automatically
curl -X POST https://api.bouncerly.com/v1/jobs \
  -H "Authorization: Bearer bn_123456789" \
  -F file=@contacts.csv \
  -F name="October newsletter" \
  -F webhook_url=https://example.com/hooks/verify

# Download the cleaned list when it's done
curl "https://api.bouncerly.com/v1/jobs/{id}/results?format=csv&status=deliverable" \
  -H "Authorization: Bearer bn_123456789" -o clean.csv

202 Accepted

{"id": "79f348c5-…", "name": "October newsletter", "status": "queued", "total": 5000, "processed": 0, "created_at": "…", "completed_at": null}

A job reserves its size against your monthly quota when it's created. If it doesn't fit, you get a 402 quota_exceeded error that says how many checks you have left.

Check progress and get results

GET/v1/jobs/{id}

Returns progress and counts by status (pending, deliverable, …).

GET/v1/jobs/{id}/results

Query	Description
`format=csv`	CSV instead of JSON: email, status, reason, did_you_mean, flags, mx_host, smtp_code, smtp_message.
`status=deliverable,risky`	Only return these statuses. Works with both formats.

GET/v1/jobs?limit=50

Lists your workspace's recent jobs.

DELETE/v1/jobs/{id}

Cancels unfinished work. Addresses already checked keep their results.

Greylisted and temporarily failing addresses are retried after 10 and then 20 minutes before they're reported as unknown, so the last few items of a job can finish a while after the rest.