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://app.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 classification returned:

Test address	classification	score
[email protected]	verified	98
[email protected]	invalid	2
[email protected]	catch_all	50
[email protected]	disposable	10
[email protected]	risky	25
[email protected] (or any other local part)	unknown	50

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. Manage webhooks and view delivery logs from your Dashboard.

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.

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 HTTP(S).

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]", "classification": "verified", "score": 95, "reason": "Mailbox verified and all checks passed", "signals": { "syntax_valid": true, "mx_found": true, "smtp_verified": true, "is_disposable": false, "is_role_based": false, "is_catch_all": false, "has_social_presence": true }, "domain": { "name": "example.com", "provider": "Google Workspace", "has_mx": true, "has_spf": true, "has_dmarc": true } }

Response Fields

Field	Type	Description
status	string	deliverable, undeliverable, risky, or unknown
score	integer	Confidence score from 0 (bad) to 100 (perfect)
reason	string	Human-readable explanation of the result
signals	object	Detailed signal breakdown from each pipeline stage
domain	object	Domain information including DNS records and provider

Code Examples

curl -X POST https://app.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://app.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://app.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.status, 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 come back unknown 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://app.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": "bulk_abc123def456",
  "total_emails": 3,
  "status": "processing"
}

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://app.bouncezero.io/api/v1/verify/bulk/upload \ -H "X-API-Key: YOUR_API_KEY" \ -F "[email protected]"

Response

200 OK

{
  "job_id": "bulk_xyz789ghi012",
  "total_emails": 1500,
  "status": "processing"
}

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": "bulk_abc123def456",
  "status": "processing",
  "total": 3,
  "processed": 2,
  "progress_pct": 66.7
}

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": "bulk_abc123def456", "status": "completed", "results": [ { "email": "[email protected]", "classification": "verified", "score": 95, "reason": "Mailbox verified" }, { "email": "[email protected]", "classification": "invalid", "score": 12, "reason": "Mailbox does not exist" } ] }

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://app.bouncezero.io/api/v1/verify/bulk/bulk_abc123def456/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://app.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

Each verified email address is assigned a classification - returned in the classification field - based on the analysis of all 40+ signals.

verified

The email address is valid and safe to send to. The mailbox exists, the domain has valid MX records, and SMTP verification confirmed deliverability. This is the highest confidence result.

invalid

The email address is invalid or the mailbox does not exist. Sending to this address will result in a hard bounce. Common causes include non-existent mailboxes, invalid domains, or syntax errors.

catch_all

The domain accepts mail for any address (accept-all), so the individual mailbox could not be confirmed via SMTP. Deliverability is uncertain.

disposable

The address belongs to a disposable / temporary email provider. The mailbox is short-lived and engagement value is near zero.

risky

The address shows concrete negative signals - for example a persistently full mailbox, reputation problems on the domain, or a history of bounces - that make delivery unreliable. Send with caution.

unknown

The verification could not be completed. The domain's mail server may be temporarily unavailable, blocking verification attempts, or using a greylisting strategy. We recommend retrying these addresses later.

Two rare threat classifications may also appear: complainer (a history of marking mail as spam) and spamtrap (a known spam-trap address). Remove both from your lists immediately - details are provided in the threat_type field.