API Documentation

Authentication

All API requests require an API key passed in the X-API-Key header.

1. Log in to your dashboard
2. Navigate to Settings > API Keys
3. Click Generate API Key
4. Copy your key (starts with bz_live_)

X-API-Key: bz_live_your_key_here

Keep your API key secret. Do not expose it in client-side code or public repositories.

Single Email Verification

JSON Body

Example Response

{
  "email": "[email protected]",
  "score": 95,
  "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
  },
  "explanation": "Mailbox exists and is deliverable"
}

Bulk Verification

Upload a CSV file of emails for batch verification. Three endpoints are used in sequence. To send a JSON list instead (up to 10,000 emails), POST /api/v1/verify/bulk with {"emails": [...]} and an optional Idempotency-Key header.

1. Upload CSV

Send a multipart/form-data request with a CSV file (form field file) containing one email per row, or a header row with an email column.

# Response
{
  "job_id": "a1b2c3d4-e5f6-...",
  "total_emails": 5000,
  "deduplicated": 4812,
  "status": "queued"
}

2. Check Status

{
  "job_id": "a1b2c3d4-e5f6-...",
  "status": "processing",
  "progress": {
    "total": 4812,
    "completed": 3200,
    "percent": 66.5
  }
}

Statuses: queued, processing, interrupted (resumes automatically, keep polling), and the final states completed, failed, stopped, credits_exhausted.

3. Get Results

Returns results as JSON, paginated with ?limit= (max 5000) and ?offset=. For a CSV file use GET /api/v1/verify/bulk/{job_id}/download.

Response Fields

Result Values

Score

Each email receives a deliverability score from 0 to 100. This score combines SMTP probing, DNS validation, provider-specific checks, and machine learning signals.

Error Codes

Webhooks

Receive notifications when bulk jobs complete. Configure your webhook URL in Dashboard > Settings > Webhooks.

Payload

{
  "event": "bulk.completed",
  "job_id": "a1b2c3d4-e5f6-...",
  "timestamp": "2026-04-22T14:30:00Z",
  "stats": {
    "total": 4812,
    "valid": 3901,
    "invalid": 911
  }
}

Webhooks include an X-BounceZero-Signature header for HMAC-SHA256 verification using your webhook signing secret.

Sandbox Mode

Test your integration without consuming credits. Grab a sandbox key instantly below, or generate one from Dashboard > Settings > API Keys > Create Sandbox Key.

Test Addresses

Sandbox keys are rate-limited to 30 requests per minute. The local part selects the result; also try disposable@ and risky@.

Code Examples

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

import requests

API_KEY = "bz_live_your_key_here"

response = requests.post(
    "https://api.bouncezero.io/api/v1/verify",
    json={"email": "[email protected]"},
    headers={"X-API-Key": API_KEY},
)

data = response.json()
print(f"Result: {data['classification']}, Score: {data['score']}")

const API_KEY = "bz_live_your_key_here";

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

const data = await res.json();
console.log(`Result: ${data.classification}, Score: ${data.score}`);

<?php
$apiKey = "bz_live_your_key_here";

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL => "https://api.bouncezero.io/api/v1/verify",
    CURLOPT_HTTPHEADER => ["X-API-Key: $apiKey", "Content-Type: application/json"],
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode(["email" => "[email protected]"]),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERAGENT => "MyApp/1.0",
]);
$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo "Result: {$data['classification']}, Score: {$data['score']}";