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.

Limit	Value	Details
Requests per minute	100	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.

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": "test@example.com"
}

Response

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

200 OK

{
  "email": "test@example.com",
  "status": "deliverable",
  "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": "test@example.com"}'

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": "test@example.com"}
)

data = response.json()
print(data["status"], 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: "test@example.com" })
});

const data = await response.json();
console.log(data.status, data.score);

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": "test@example.com"
}

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": "test@example.com"}'

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": [
    "alice@example.com",
    "bob@example.com",
    "charlie@example.com"
  ]
}

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.

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 "file=@emails.csv"

Response

200 OK

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

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": "alice@example.com",
      "status": "deliverable",
      "score": 95,
      "reason": "Mailbox verified"
    },
    {
      "email": "bob@example.com",
      "status": "undeliverable",
      "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": []
}

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.
403	Forbidden	Your account does not have access to this resource, or you have insufficient credits.
429	Rate Limited	You have exceeded the rate limit of 100 requests per minute. 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 one of four statuses based on the analysis of all 40+ signals.

deliverable

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.

undeliverable

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.

risky

The email address may be deliverable but carries risk. This includes catch-all domains (accept everything, but may silently discard), disposable email addresses, role-based addresses (e.g., info@, admin@), or addresses with low sender reputation history.

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.