ZeroBouncer API Docs

API Documentation

Build with the ZeroBouncer API using your dashboard API key. This guide covers authentication, request format, response fields, and production-ready integration details.

Overview

Base URL (Production): https://zerobouncer.com/api/v1

Primary client endpoint for API key usage: POST /verify/api

Quick Start

Create an account and open Dashboard.
Go to API Keys and click Create New Key.
Store key securely. It is shown once.
Call verify endpoint with x-api-key header.

cURL

curl -X POST "https://zerobouncer.com/api/v1/verify/api" \
  -H "Content-Type: application/json" \
  -H "x-api-key: zb_live_xxxxxxxxxxxxx" \
  -d '{"email":"user@example.com"}'

Authentication

Send your API key in the x-api-key header for each API request.

x-api-key: zb_live_xxxxxxxxxxxxx

If the key is missing, invalid, disabled, or deleted, the request will fail with unauthorized/forbidden response.

Single Email Verify

Endpoint: POST /verify/api

Headers: Content-Type: application/json, x-api-key: YOUR_KEY

Request Body

{
  "email": "user@example.com"
}

Response (JSON)

HTTP/1.1 200 OK
{
  "result": "deliverable",
  "message": "This address can receive emails.",
  "email": "support@bouncify.io",
  "user": "support",
  "domain": "bouncify.io",
  "accept_all": 2,
  "role": 1,
  "free_email": 0,
  "disposable": 0,
  "spamtrap": 0,
  "success": true
}

How To Use The Result

Apart from undeliverable, for deliverable, accept-all, and unknown do not reject the email address. Accept-all and unknown could still be valid addresses.
If the request was not successful, consider proceeding with your workflow.

Response Parameters

Parameter	Type	Definition
result	string	deliverable, undeliverable, unknown, accept all
message	string	Describes API result
email	email	The email that was verified
user	string	User part of the email
domain	string	Domain part of the email
accept_all	integer	Remote host accepts mail at any address
role	0 or 1	Whether email is role based (sales, info, help, etc.)
free_email	0 or 1	Whether email is from free provider (Gmail, Yahoo, etc.)
disposable	0 or 1	Whether email is temporary/disposable
spamtrap	0 or 1	Whether email is honeytrap
success	true or false	Whether API request was successful

Other Responses

HTTP/1.1 400 Bad Request
{
  "result": "Invalid request. Required email.",
  "success": false
}

HTTP/1.1 401 Unauthorized
{
  "success": "false",
  "result": "Invalid API Key"
}

HTTP/1.1 402 Payment Required
{
  "success": "false",
  "result": "Insufficient verification credits"
}

HTTP/1.1 429 Too Many Requests
{
  "success": "false",
  "result": "Too many requests"
}

Bulk Email Verify API

Option 1: CSV file

This endpoint accepts only .csv format. Maximum file size is 10MB. Maximum emails per list is 500,000. Additional columns are retained and included in the output file.

Endpoint

POST /bulk/api/upload (multipart/form-data)

curl --request POST \
  --url https://zerobouncer.com/api/v1/bulk/api/upload \
  --header 'x-api-key: zb_live_xxxxxxxxxxxxx' \
  --form 'file=@emails.csv' \
  --form 'name=My CSV List' \
  --form 'auto_verify=true'

Option 2: Array of emails

You can submit JSON directly without creating a file. Each object must include an email field and may include any additional fields.

Endpoint

POST /bulk/api/create (application/json)

{
  "auto_verify": "true",
  "emails": [
    {
      "email": "test1@example.com",
      "firstname": "John",
      "lastname": "Doe"
    },
    {
      "email": "test2@example.com",
      "firstname": "Daniel",
      "lastname": "Jay"
    }
  ]
}

Limits

Maximum 500 unverified lists per account
Maximum 100 active verification lists concurrently
Maximum 500,000 emails per list
CSV upload size limit: 10MB

Successful Response

HTTP/1.1 200 OK
{
  "job_id": "r374aki32rnatv868nntpxloc7dkilszc3eu",
  "success": true,
  "message": "Bulk email verification list has been created"
}

Response Parameters

job_id (string): Created list/job identifier
success (boolean): API call result
message (string): Result message

Other Responses

HTTP/1.1 401 Unauthorized
{
  "result": "Invalid API Key",
  "success": false
}

HTTP/1.1 200 OK
{
  "job_id": "r374aki32rnatv868nntpxloc7dkilszc3eu",
  "success": true,
  "message": "Bulk email verification list has been created and starts verification shortly, subjected to verification credits availability"
}

HTTP/1.1 400 BadRequest
{
  "result": "Invalid file data",
  "success": false
}

HTTP/1.1 400 BadRequest
{
  "success": false,
  "message": "The maximum number of lists has been reached."
}

HTTP/1.1 400 BadRequest
{
  "success": false,
  "message": "The maximum number of active verification lists has been reached."
}

Job Management APIs

GET /bulk/api/jobs
GET /bulk/api/jobs/:id
GET /bulk/api/jobs/:id/download
PATCH /bulk/api/jobs/:id/cancel

Response Fields

valid: Final deliverability decision

syntaxValid: Email format is valid

domainValid: Domain resolves correctly

mxValid: MX records exist for domain

smtpValid: SMTP mailbox check result

isDisposable: Disposable provider flag

isCatchAll: Catch-all domain flag

qualityScore: Quality score 0-100

responseTime: Verification time in ms

reason: Human-readable decision reason

Errors and Status Codes

Status	When It Happens
400	Invalid request body or malformed email
401	Missing or invalid API key
402/403	Not enough credits or key access blocked
429	Rate limit exceeded
500	Unexpected server error, retry with backoff

Dashboard API Key Endpoints

These endpoints are for your dashboard app (JWT auth required) to manage keys.

POST /api-keys: Create API key

GET /api-keys: List API keys

PATCH /api-keys/:id/toggle: Enable or disable key

DELETE /api-keys/:id: Delete key

Integration Notes

Always verify on server side for security.
Do not expose live API keys in frontend code.
Implement retry with exponential backoff on 429 and 5xx responses.
Store verification responses for audit and analytics.

Create Account Open Dashboard