BounceBan Email Verification

Verify emails via the BounceBan API. BounceBan specializes in accept-all (catch-all) emails and emails protected by Secure Email Gateways - it identifies which accept-all emails are actually deliverable instead of marking them all as risky.

Setup

• API key: read from $BOUNCEBAN_API_KEY (get one at https://bounceban.com/app/api/settings).
• Auth: send the key in the Authorization header, no Bearer prefix.
• Base URL: https://api.bounceban.com (exception: waterfall endpoint uses https://api-waterfall.bounceban.com).
• Each verification costs 1 credit. Check balance with GET /v1/account.

curl -s "https://api.bounceban.com/v1/account" -H "Authorization: $BOUNCEBAN_API_KEY"

Choosing an endpoint

Read the matching reference file before calling an endpoint you haven't used in this session. references/introduction.md covers auth, credits, result enums, and rate limits in full.

Quick recipes

Verify one email and wait (recommended default; holds connection up to 80 s):

curl -s "https://api-waterfall.bounceban.com/v1/verify/single?email=someone@example.com" \
  -H "Authorization: $BOUNCEBAN_API_KEY"

Verify a list:

# 1. Create task -> returns {"id": ...}
curl -s -X POST "https://api.bounceban.com/v1/verify/bulk" \
  -H "Authorization: $BOUNCEBAN_API_KEY" -H "Content-Type: application/json" \
  -d '{"emails": ["a@example.com", "b@example.com"]}'
# 2. Poll until status=finished
curl -s "https://api.bounceban.com/v1/verify/bulk/status?id=TASK_ID" \
  -H "Authorization: $BOUNCEBAN_API_KEY"
# 3. Fetch results (cursor pagination; loop until cursor is null)
curl -s "https://api.bounceban.com/v1/verify/bulk/dump?id=TASK_ID&page_size=1000" \
  -H "Authorization: $BOUNCEBAN_API_KEY"

Reading results

• result: deliverable (safe) | risky (check score, higher is better) | undeliverable (will bounce) | unknown.
• score: 0-100 deliverability confidence.
• Flags: is_disposable, is_accept_all, is_role, is_free; plus mx_records, smtp_provider.
• Optional mode=deepverify parameter improves accept-all accuracy when the email domain matches the owner's company website (e.g. sourced from LinkedIn).

Critical rules (violating these wastes the user's credits)

1. Never resubmit an email while its status is verifying or queue - every submit to /v1/verify/single costs 1 credit. Poll /v1/verify/single/status instead (free).
2. Waterfall endpoint HTTP 408 = timeout, not failure: retry the same request; retries within 30 minutes are free.
3. Polling cap: max 10 polls per verification id per 5 minutes; after 5 minutes without a result, start a new verification instead.
4. Bulk export links expire after 4 hours; results are retained for 90 days.
5. POST /v1/verify/bulk/destroy is irreversible - confirm with the user first.
6. For /v1/verify/bulk/file, the file field must be the LAST field in the multipart form.
7. Rate limits: /verify/single 25/s, /verify/bulk 3/s, others 25/s (live values: GET /v1/account).

Error handling