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

Query Parameters

Example Response

{
  "email": "[email protected]",
  "result": "valid",
  "score": 95,
  "smtp_check": true,
  "mx_check": true,
  "disposable": false,
  "free_provider": true,
  "catch_all": false,
  "reason": "Mailbox exists and is deliverable"
}

Bulk Verification

Upload a CSV file of emails for batch verification. Three endpoints are used in sequence.

1. Upload CSV

Send a multipart/form-data request with a CSV 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": "processing"
}

2. Check Status

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

3. Get Results

Returns results once status is completed. Supports ?format=csv or ?format=json (default).

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. Generate a sandbox key from Dashboard > Settings > API Keys > Create Sandbox Key.

Test Addresses

Sandbox keys are rate-limited to 10 requests per minute.

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['result']}, 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.result}, 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,
]);
$response = curl_exec($ch);
curl_close($ch);

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