Developers

API reference

Verify one address in real time, or send a whole list as a batch. All requests use HTTPS and return JSON. API keys are issued from your dashboard when accounts open.

Authentication

Send your API key as a bearer token in the Authorization header on every request. Keep keys on your server. Never put them in browser code or mobile apps.

Authorization: Bearer YOUR_API_KEY

The base URL for every endpoint is https://api.bouncebell.com/v1.

Verify one address

GET https://api.bouncebell.com/v1/verify

Parameter	Required	Description
`email`	Yes	The address to check. URL-encode it.
`timeout`	No	Seconds to wait for the mail server, from 3 to 30. Default 10. If time runs out, the status is `unknown` and no credit is used.

Example

curl "https://api.bouncebell.com/v1/verify?email=priya%40acme-foods.example" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "email": "priya@acme-foods.example",
  "status": "valid",
  "reason": "mailbox_exists",
  "domain": "acme-foods.example",
  "mx_record": "mx1.acme-foods.example",
  "disposable": false,
  "role": false,
  "free_provider": false,
  "did_you_mean": null,
  "checked_at": "2026-10-30T09:30:12Z",
  "credits_used": 1
}

Result fields

Field	Type	Description
`email`	string	The address as you sent it.
`status`	string	The verdict. See statuses.
`reason`	string	Why we reached the verdict, for example `mailbox_not_found` or `no_mx_record`.
`domain`	string	The domain part, in lower case.
`mx_record`	string or null	The mail server with the highest priority.
`disposable`	boolean	True if the domain is a temporary inbox service.
`role`	boolean	True for shared inboxes such as info@ or support@.
`free_provider`	boolean	True for free mailbox providers such as Gmail.
`did_you_mean`	string or null	A corrected address when the domain looks like a typo.
`checked_at`	string	When the check ran, in ISO 8601 UTC.
`credits_used`	integer	1, or 0 when the status is `unknown`.

Statuses

Status	Meaning	Suggested action
`valid`	The mailbox exists and accepts mail.	Send
`invalid`	The address, domain or mailbox does not exist.	Remove
`disposable`	A temporary inbox service.	Remove
`catch_all`	The domain accepts all addresses, so the mailbox cannot be confirmed.	Review
`role`	A shared inbox that exists.	Review
`unknown`	The mail server did not give an answer in time. Not charged.	Retry later

Batches

Send up to 100,000 addresses in one request. The batch runs in the background; poll for its status or give a callback_url and we will call it when the batch is finished.

Create a batch

POST https://api.bouncebell.com/v1/batches

curl -X POST "https://api.bouncebell.com/v1/batches" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "October import", "emails": ["a@example.com", "b@example.com"],
       "callback_url": "https://yourapp.example/hooks/bouncebell"}'

{ "id": "bat_8f2k1q", "status": "queued", "total": 2 }

Check progress

GET https://api.bouncebell.com/v1/batches/{id}

{ "id": "bat_8f2k1q", "status": "running", "total": 2, "done": 1 }

Download results

GET https://api.bouncebell.com/v1/batches/{id}/results

Returns JSON by default. Add ?format=csv for a CSV file. Each row has the same fields as a single check.

Credits

GET https://api.bouncebell.com/v1/credits

{ "monthly_remaining": 8420, "payg_remaining": 25000, "renews_at": "2026-11-30" }

Errors and limits

Errors return a JSON body with an error code and a readable message.

HTTP code	Error	What to do
400	`bad_request`	A parameter is missing or wrong. Read the message.
401	`invalid_key`	Check the key is correct and has not been revoked.
402	`no_credits`	Buy credits or wait for your monthly renewal.
429	`rate_limited`	Slow down. Wait for the seconds in the `Retry-After` header.
500	`server_error`	Retry with a short delay. If it continues, contact support.

Single checks are limited to 20 requests per second per key. Ask us if you need more.