API Documentation

Integrate BounceZero email verification into your applications.

The BounceZero API provides programmatic access to our 5-stage email verification pipeline. Every email address is evaluated across 40+ signals including syntax validation, DNS and MX record analysis, SMTP mailbox probing, disposable and role-based detection, social signal checks, and Bayesian + ML scoring.

Use the API to verify individual emails in real time, process bulk lists asynchronously, query detailed domain intelligence, and manage your account programmatically.

Quick start: Sign up for a free account to get 100 verification credits every month. No credit card required.

Pipeline Stages

1

Syntax & Format

RFC 5322 validation, typo detection

2

Domain & DNS

MX records, SPF, DKIM, DMARC checks

3

SMTP Verification

Mailbox probing, catch-all detection

4

Intelligence Signals

Disposable, role-based, social presence

5

Bayesian + ML Scoring

Composite score (0-100) with AI-powered explanations and confidence weighting

Authentication

All API requests require authentication via an API key. Include your key in the X-API-Key request header.

You can obtain your API key from the Dashboard under the Integration page. Keep your API key secret and never expose it in client-side code.

Header

X-API-Key: YOUR_API_KEY

Important: Never include your API key in frontend JavaScript or public repositories. Use server-side requests to protect your credentials.

Base URL

All API endpoints are relative to the following base URL:

Base URL

https://api.bouncezero.io/api/v1

All requests must be made over HTTPS. HTTP requests will be rejected.

Rate Limits

API requests are rate-limited to ensure fair usage and platform stability.

Plan	Requests per minute	Details
Free	30	Per API key, across all endpoints
Starter / Growth	100	Per API key, across all endpoints
Professional / Business / Scale	300	Per API key, across all endpoints
Ultimate / Enterprise	1000	Per API key, across all endpoints

When you exceed the rate limit, the API returns a 429 Too Many Requests response. Implement exponential backoff in your integration to handle rate limiting gracefully.

Every authenticated response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers so your client can pace itself before hitting the limit.

Sandbox / Test Mode

Sandbox API keys (prefix bz_test_) let you build and test your integration without consuming credits or triggering real verifications. Every request made with a sandbox key returns a deterministic mock result - no SMTP probe is performed and your balance is never touched.

The local part of the email address you submit selects the internal class. Sandbox responses follow the same binary contract as live keys: classification is valid or invalid, and the selected class is returned in metadata.internal_classification:

Test address	classification	metadata.internal_classification	score	metadata flags
[email protected]	valid	verified	98
[email protected]	invalid	invalid	2
[email protected]	valid	catch_all	50	catch_all_unresolved: true
[email protected]	invalid	disposable	10
[email protected]	invalid	risky	25
[email protected] (or any other local part)	invalid	unknown	50	refunded: true

Any domain works - only the local part matters. Sandbox responses are marked with "confidence": "sandbox" so you can always tell them apart from live results. Rate limits still apply.

Note: Sandbox keys never perform real verification - do not use them in production. Currently supported on POST /api/v1/verify. Generate a sandbox key from your Dashboard.

Webhooks

Webhooks notify your server when asynchronous work finishes, so you don't have to poll job status. They fire for bulk jobs submitted through the API as well as from the dashboard. Manage webhooks and view delivery logs from your Dashboard, or register one with the API:

POST /api/v1/webhooks?url={https_url}

url is a query parameter and must be a public https:// URL. The optional request body is a JSON array of event names; omit it to subscribe to all events. Registering the same URL again updates its events.

cURL - register a webhook

curl -X POST "https://api.bouncezero.io/api/v1/webhooks?url=https://example.com/bz-hook" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '["job.completed"]'

# {"status": "registered", "url": "https://example.com/bz-hook", "events": ["job.completed"]}

Event	Fires when
job.completed	A bulk verification job finishes processing.
job.stopped	A bulk job is stopped before completion.
job.escalated	A bulk job needs attention (e.g., a processing problem was detected).
test	Sent when you use the "Test" button in the dashboard.

job.completed payload

{
  "event": "job.completed",
  "data": {
    "job_id": "3f2b9c1e-8a4d-4f6b-9e2a-7c5d1b0a9e33",
    "total": 1500,
    "completed": 1500,
    "status": "completed"
  }
}

Deliveries are JSON POST requests with two headers: X-BounceZero-Event (the event name) and X-BounceZero-Signature (an HMAC-SHA256 of the raw request body, prefixed with sha256=). Your signing secret is shown in the dashboard's webhook settings. Always verify the signature before trusting a payload:

Python - verify signature

import hmac, hashlib

def verify_signature(raw_body: bytes, header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)

Failed deliveries are retried up to 3 times with exponential backoff (1s, 2s, 4s). Endpoints that fail 5 consecutive deliveries are automatically disabled - re-enable them from the dashboard after fixing your receiver. Webhook URLs must be publicly reachable over HTTPS.

Client Libraries

New - official SDKs are here. Install straight from PyPI, npm, and Packagist. Each client is open source (MIT) and available on GitHub.

Official clients with automatic retries (429/5xx with backoff), typed errors, bulk-job helpers, idempotency support, and webhook signature verification - with zero external dependencies.

Language	Install	Package	Source
Python 3.8+	pip install bouncezero	PyPI	GitHub
Node.js 18+	npm install bouncezero	npm	GitHub
PHP 8.0+	composer require bouncezero/bouncezero	Packagist	GitHub

Python

from bouncezero import BounceZero client = BounceZero("bz_live_...") result = client.verify("[email protected]") print(result["classification"], result["score"]) job = client.verify_bulk(emails, idempotency_key="order-1234") final = client.wait_for_bulk(job["job_id"]) csv_bytes = client.bulk_download(job["job_id"])

Node.js

const BounceZero = require("bouncezero"); const client = new BounceZero("bz_live_..."); const result = await client.verify("[email protected]"); console.log(result.classification, result.score); const job = await client.verifyBulk(emails, { idempotencyKey: "order-1234" }); const final = await client.waitForBulk(job.job_id); const csv = await client.bulkDownload(job.job_id);

PHP

require 'vendor/autoload.php'; use BounceZero\BounceZero; $client = new BounceZero('bz_live_...'); $result = $client->verify('[email protected]'); echo $result['classification'], ' ', $result['score']; $job = $client->verifyBulk($emails, 'order-1234'); $final = $client->waitForBulk($job['job_id']); $csv = $client->bulkDownload($job['job_id']);

Every client ships a webhook helper - e.g. BounceZero.verify_webhook_signature(raw_body, header, secret) - so you can validate X-BounceZero-Signature in one line. Test your integration risk-free with a sandbox key. Prefer to vendor a single file instead? Download Python, Node.js, or PHP directly.

Verify Single Email

Verify a single email address through the full 5-stage pipeline.

POST /api/v1/verify

Request Headers

Header	Value	Required
Content-Type	application/json	Yes
X-API-Key	Your API key	Yes

Request Body

JSON

{ "email": "[email protected]" }

Response

A successful response returns the verification result with a full signal breakdown.

200 OK

{ "email": "[email protected]", "score": 98, "classification": "valid", "is_deliverable": true, "risk_level": "low", "checks": { "syntax": true, "domain_valid": true, "not_disposable": true, "not_catch_all": true, "mailbox_verified": true }, "metadata": { "internal_classification": "verified", "refunded": null, "catch_all_unresolved": null, "response_time_ms": 412 } }

Response Fields

Field	Type	Description
classification	string	valid or invalid (binary). See Verification Statuses
score	integer	Confidence score from 0 (bad) to 100 (perfect)
is_deliverable	boolean	true when classification is valid
risk_level	string	low, medium, or high
checks	object	Per-check booleans: syntax, domain_valid, not_disposable, not_catch_all, mailbox_verified, and more
metadata.internal_classification	string	Detailed internal class: verified, likely_valid, catch_all, invalid, risky, unknown, disposable, spamtrap, or error
metadata.refunded	boolean \| null	true when the address could not be verified; reported as invalid and the credit is refunded automatically
metadata.catch_all_unresolved	boolean \| null	true for a catch-all domain that could not be resolved individually; still reported as valid

Code Examples

curl -X POST https://api.bouncezero.io/api/v1/verify \ -H "Content-Type: application/json" \ -H "X-API-Key: YOUR_API_KEY" \ -d '{"email": "[email protected]"}'

import requests response = requests.post( "https://api.bouncezero.io/api/v1/verify", headers={ "Content-Type": "application/json", "X-API-Key": "YOUR_API_KEY" }, json={"email": "[email protected]"} ) data = response.json() print(data["classification"], data["score"])

const response = await fetch("https://api.bouncezero.io/api/v1/verify", { method: "POST", headers: { "Content-Type": "application/json", "X-API-Key": "YOUR_API_KEY" }, body: JSON.stringify({ email: "[email protected]" }) }); const data = await response.json(); console.log(data.classification, data.score);

Verify Batch

Synchronously verify up to 100 addresses in one request - the call returns once every address is processed. For larger lists, use the asynchronous bulk endpoints.

POST /api/v1/verify/batch

Request Body

{ "emails": ["[email protected]", "[email protected]"] }

The response contains a results array (one object per address, same fields as single verification) and a summary object with per-classification counts.

Costs 1 credit per address. Credits for addresses that could not be verified (metadata.refunded: true) are refunded automatically.

Verify Realtime (SSE)

Stream verification results in real time using Server-Sent Events.

POST /api/v1/verify/realtime

This endpoint uses Server-Sent Events (SSE) to stream verification progress as it happens. Each pipeline stage emits an event as it completes, allowing you to display live progress to users.

Request Body

JSON

{ "email": "[email protected]" }

Example (cURL)

cURL

curl -X POST https://api.bouncezero.io/api/v1/verify/realtime \ -H "Content-Type: application/json" \ -H "X-API-Key: YOUR_API_KEY" \ -H "Accept: text/event-stream" \ -d '{"email": "[email protected]"}'

The response is delivered as an SSE stream. Each event contains a JSON payload with the current stage and partial results. The final event contains the complete verification result.

Verify Bulk (JSON)

Submit a batch of emails for asynchronous verification.

POST /api/v1/verify/bulk

Request Body

JSON

{ "emails": [ "[email protected]", "[email protected]", "[email protected]" ] }

Response

200 OK

{
  "job_id": "3f2b9c1e-8a4d-4f6b-9e2a-7c5d1b0a9e33",
  "total_emails": 3,
  "deduplicated": 3,
  "status": "queued"
}

Use the returned job_id to poll for status, retrieve results, or download the completed CSV.

Idempotency: pass an optional Idempotency-Key header (any unique string, max 255 chars) to make retries safe. If a request with the same key is submitted again - for example after a network timeout - the API returns the original job (with an X-Idempotent-Replay: true response header) instead of creating and charging for a duplicate.

Verify Bulk (CSV Upload)

Upload a CSV file containing email addresses for bulk verification.

POST /api/v1/verify/bulk/upload

Send the CSV file as multipart form data. The CSV should contain email addresses, one per row. A header row with email as the column name is recommended.

Example (cURL)

cURL

curl -X POST https://api.bouncezero.io/api/v1/verify/bulk/upload \ -H "X-API-Key: YOUR_API_KEY" \ -F "[email protected]"

Response

200 OK

{
  "job_id": "3f2b9c1e-8a4d-4f6b-9e2a-7c5d1b0a9e33",
  "total_emails": 1500,
  "deduplicated": 1500,
  "status": "queued"
}

Idempotency: this endpoint also honors the Idempotency-Key header - replaying the same key returns the original job (with X-Idempotent-Replay: true) instead of creating and charging for a duplicate.

Bulk Job Status

Check the progress and status of a bulk verification job.

GET /api/v1/verify/bulk/{job_id}/status

Response

200 OK

{
  "job_id": "3f2b9c1e-8a4d-4f6b-9e2a-7c5d1b0a9e33",
  "status": "processing",
  "progress": {
    "total": 3,
    "completed": 2,
    "percent": 66.7
  }
}

status is one of queued, processing, interrupted, completed, failed, stopped, or credits_exhausted. An interrupted job resumes automatically, so keep polling; only completed, failed, stopped, and credits_exhausted are final.

Bulk Job Results

Retrieve the verification results for a completed bulk job as JSON.

GET /api/v1/verify/bulk/{job_id}/results

Response

200 OK

{
  "job_id": "3f2b9c1e-8a4d-4f6b-9e2a-7c5d1b0a9e33",
  "status": "completed",
  "total": 2,
  "completed": 2,
  "results": [
    {
      "email_hash": "5d41402abc4b2a76...",
      "score": 95,
      "classification": "valid",
      "is_deliverable": true,
      "metadata": { "internal_classification": "verified" }
    },
    {
      "email_hash": "7d793037a0760186...",
      "score": 12,
      "classification": "invalid",
      "is_deliverable": false,
      "metadata": { "internal_classification": "invalid" }
    }
  ],
  "pagination": { "limit": 1000, "offset": 0, "has_more": false }
}

Bulk Job Download

Download the results of a completed bulk job as a CSV file.

GET /api/v1/verify/bulk/{job_id}/download

Returns a CSV file with the verification results. The response Content-Type is text/csv. Only available once the job status is completed.

Example

cURL

curl -X GET https://api.bouncezero.io/api/v1/verify/bulk/3f2b9c1e-8a4d-4f6b-9e2a-7c5d1b0a9e33/download \
  -H "X-API-Key: YOUR_API_KEY" \
  -o results.csv

Domain Lookup

Retrieve comprehensive intelligence about an email domain.

GET /api/v1/domain/{domain}

Returns detailed domain intelligence including MX records, SPF, DKIM and DMARC configuration, email provider identification, and risk indicators.

Example

cURL

curl https://api.bouncezero.io/api/v1/domain/example.com \
  -H "X-API-Key: YOUR_API_KEY"

Response

200 OK

{
  "domain": "example.com",
  "mx_records": [
    { "priority": 10, "host": "mail.example.com" }
  ],
  "has_spf": true,
  "has_dkim": true,
  "has_dmarc": true,
  "provider": "Google Workspace",
  "is_disposable": false,
  "is_free_provider": false,
  "risk_indicators": []
}

Analyze List

Free pre-flight quality analysis of an email list - no verification is performed and no credits are consumed. Use it to gauge list quality before paying for a bulk job.

POST /api/v1/analyze/list

Request Body

{ "emails": ["[email protected]", "[email protected]"] }

Returns a quality_score (0-100), total / unique counts, an estimated classification distribution, list-hygiene metrics (duplicates, disposable, role-based, ...), warnings, and actionable recommendations.

Get API Key

Retrieve your current API key.

GET /api/v1/user/api-key

Response

200 OK

{
  "api_key": "bz_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

Generate API Key

Generate a new API key. This will invalidate your previous key.

POST /api/v1/user/api-key/generate

Warning: Generating a new key immediately revokes the previous one. All integrations using the old key will stop working.

Response

200 OK

{
  "api_key": "bz_live_yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy",
  "created_at": "2026-02-18T12:00:00Z"
}

API Usage Stats

Retrieve your API usage statistics.

GET /api/v1/user/api-usage

Response

200 OK

{
  "total_requests": 4820,
  "requests_today": 127,
  "requests_this_month": 2340,
  "last_request_at": "2026-02-18T10:35:12Z"
}

Check Balance

Check your remaining verification credit balance.

GET /api/v1/user/balance

Response

200 OK

{
  "credits_remaining": 7650,
  "free_credits": 42,
  "paid_credits": 7608
}

Response Codes

The API uses standard HTTP status codes to indicate the outcome of each request.

Code	Status	Description
200	OK	Request succeeded. Response body contains the requested data.
400	Bad Request	The request body is missing or contains invalid parameters (e.g., malformed email address).
401	Unauthorized	Missing or invalid API key. Check that the X-API-Key header is present and correct.
402	Payment Required	Insufficient credits to perform this verification. Top up your balance in the dashboard.
422	Validation Error	The request body failed validation (wrong types or missing required fields).
403	Forbidden	Your account does not have access to this resource (e.g., the API key is disabled, expired, or IP-restricted).
429	Rate Limited	You have exceeded your plan's per-minute rate limit. Wait and retry with exponential backoff.
500	Internal Error	An unexpected server error occurred. If the problem persists, contact support.

Error Response Format

Error Response

{
  "error": "Invalid API key",
  "code": 401
}

Verification Statuses

The classification field is binary: every address is returned as either valid or invalid, based on the analysis of all 40+ signals.

valid

The address is deliverable and safe to send to. Covers confirmed mailboxes (verified), strong multi-signal results (likely_valid), and catch-all domains that could not be resolved individually (catch_all, flagged with metadata.catch_all_unresolved: true and risk_level: medium). is_deliverable is true.

invalid

Do not send to this address. Covers definitive rejections (non-existent mailboxes, invalid domains, syntax errors), disposable providers, known spamtrap addresses, addresses with concrete negative signals (risky), and addresses that could not be verified (unknown). is_deliverable is false and risk_level is high. When the address could not be verified, metadata.refunded is true and the credit is refunded automatically.

Internal classification

The detailed class behind each verdict is returned in metadata.internal_classification, so you can apply a stricter or looser policy than the binary verdict:

internal_classification	classification	Meaning
verified	valid	SMTP or provider confirmed the mailbox exists.
likely_valid	valid	Multiple positive signals, no definitive SMTP confirmation.
catch_all	valid	Domain accepts mail for any address; mailbox not individually resolved (catch_all_unresolved: true).
invalid	invalid	Mailbox or domain definitively rejected, or syntax error.
disposable	invalid	Disposable / temporary email provider.
spamtrap	invalid	Known spam-trap address. Details in threat_type.
risky	invalid	Concrete negative signals such as a persistently full mailbox or bounce history.
unknown	invalid	Could not be verified (server unavailable, greylisting, blocking). refunded: true; retry later.
error	invalid	The verification failed with an internal error.