API reference

A simple JSON-over-HTTPS API. The base URL is https://app.bouncebuster.io/api/v1. The full machine-readable spec is available at /api/v1/openapi.json.

Authentication

Pass your API key as a Bearer token. Create and revoke keys in the dashboard.

Authorization: Bearer bb_live_your_key_here

Rate limits

Requests are rate-limited per API key. Every response includes RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers. Exceeding the limit returns 429.

Endpoints

POST/v1/verify

Verify a single email address.

curl -X POST https://app.bouncebuster.io/api/v1/verify \
  -H "Authorization: Bearer bb_live_…" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]"}'

{
  "email": "[email protected]",
  "status": "valid",
  "reason": "ok",
  "catch_all": false,
  "role_based": false,
  "free_provider": false,
  "disposable": false,
  "billable": true,
  "cached": false,
  "credits_charged": 1
}

POST/v1/verify/batch

Verify up to 100 addresses in one request. Returns a result per input plus a summary. For larger volumes, create a list.

curl -X POST https://app.bouncebuster.io/api/v1/verify/batch \
  -H "Authorization: Bearer bb_live_…" \
  -H "Content-Type: application/json" \
  -d '{"emails":["[email protected]","[email protected]"]}'

POST/v1/lists

Create a bulk verification job from an array of emails. Returns a list you can poll.

curl -X POST https://app.bouncebuster.io/api/v1/lists \
  -H "Authorization: Bearer bb_live_…" \
  -H "Content-Type: application/json" \
  -d '{"name":"newsletter.csv","emails":["[email protected]","[email protected]"]}'

GET/v1/lists/{id}

Get a list’s status, counts, progress, and per-category download links (once complete).

GET/v1/lists/{id}/download/{category}

Download an export: cleaned, all, or a single category (valid, invalid, catch-all, disposable, unknown).

GET/v1/account

Return your plan, subscription status, credit usage, and current billing period.

Result fields

Field	Meaning
`status`	valid · invalid · catch-all · disposable · unknown
`reason`	Granular reason (e.g. no_mx_records, mailbox_not_found)
`catch_all`	Domain accepts all recipients
`role_based`	Address like info@, support@, sales@
`free_provider`	gmail.com, outlook.com, etc.
`disposable`	Temporary / throwaway provider
`billable`	Whether this result consumed a credit

Errors

Errors use standard HTTP status codes and a consistent JSON body:

{ "error": { "code": "no_credits", "message": "Out of credits for this billing period." } }