Single Email Verification

Verify a single email address in real-time.

Endpoint

POST /api/v1/verify

Request

Headers

Header	Required	Description
Content-Type	Yes	Must be application/json
X-API-Key	Yes	Your ClearBounce API key

Body

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

Field	Type	Required	Description
email	string	Yes	Email address to verify

Response

Success Response

{
  "success": true,
  "data": {
    "email": "user@example.com",
    "status": "deliverable",
    "subStatus": "accepted_email",
    "reason": "accepted_email",
    "score": 95,
    "isDeliverable": true,
    "toxicity": 0,
    "checks": {
      "syntax": true,
      "mxRecords": true,
      "smtpValid": true,
      "isDisposable": false,
      "isRoleBased": false,
      "isFreeProvider": false,
      "isCatchAll": false,
      "hasTypo": null,
      "patternAnalysis": {
        "suspicionScore": 0,
        "patterns": []
      },
      "account": {
        "fullMailbox": false,
        "disabled": false
      }
    },
    "meta": {
      "domain": "example.com",
      "localPart": "user",
      "mxHost": "mail.example.com",
      "smtpResponse": "250 2.1.5 OK",
      "verifiedAt": "2026-02-03T20:25:21.962Z",
      "processingTimeMs": 412,
      "provider": "example.com",
      "dnsType": "MX"
    },
    "riskFactors": []
  },
  "creditsRemaining": 999
}

Response Fields

Top Level

Field	Type	Description
success	boolean	Whether the request succeeded
data	object	Verification result
creditsRemaining	number	Your remaining credits

Data Object

Field	Type	Description
email	string	The verified email (lowercase)
status	string	deliverable, undeliverable, risky, unknown
subStatus	string | null	More specific status code
reason	string | null	Same as subStatus - human-friendly reason
score	number	Deliverability score (0-100)
isDeliverable	boolean	Whether email can receive mail (true only for deliverable)
toxicity	number	Toxicity score (0-5 scale)
checks	object	Individual check results
meta	object	Additional metadata
riskFactors	array	List of risk factor strings

Checks Object

Field	Type	Description
syntax	boolean	Email format is valid
mxRecords	boolean	Domain has MX records
smtpValid	boolean | null	Mailbox exists (null = unknown)
isDisposable	boolean	Is temporary email service
isRoleBased	boolean	Is generic address (info@, etc.)
isFreeProvider	boolean	Is free email provider
isCatchAll	boolean | null	Domain accepts all emails
hasTypo	object | null	Typo suggestion if detected
account.fullMailbox	boolean | null	Mailbox storage exceeded
account.disabled	boolean | null	Account is deactivated

Meta Object

Field	Type	Description
domain	string	Email domain
localPart	string	Part before @
mxHost	string | null	Mail server hostname
smtpResponse	string | null	Raw SMTP response
verifiedAt	string	ISO 8601 timestamp
processingTimeMs	number	Verification time in ms
provider	string | null	Email service provider
dnsType	string | null	MX or A record

Code Examples

cURL

curl -X POST https://api.clearbounce.net/api/v1/verify \
  -H "Content-Type: application/json" \
  -H "X-API-Key: cb_live_your_api_key" \
  -d '{"email": "user@example.com"}'

JavaScript (Node.js)

const response = await fetch('https://api.clearbounce.net/api/v1/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.CLEARBOUNCE_API_KEY
  },
  body: JSON.stringify({ email: 'user@example.com' })
});

const result = await response.json();

if (result.success) {
  console.log('Status:', result.data.status);
  console.log('Score:', result.data.score);
  console.log('Provider:', result.data.meta.provider);
} else {
  console.error('Error:', result.error.message);
}

Python

import requests
import os

response = requests.post(
    'https://api.clearbounce.net/api/v1/verify',
    headers={
        'Content-Type': 'application/json',
        'X-API-Key': os.environ['CLEARBOUNCE_API_KEY']
    },
    json={'email': 'user@example.com'}
)

result = response.json()

if result['success']:
    print(f"Status: {result['data']['status']}")
    print(f"Score: {result['data']['score']}")
    print(f"Provider: {result['data']['meta']['provider']}")
else:
    print(f"Error: {result['error']['message']}")

PHP

<?php
$apiKey = getenv('CLEARBOUNCE_API_KEY');

$ch = curl_init();

curl_setopt_array($ch, [
    CURLOPT_URL => 'https://api.clearbounce.net/api/v1/verify',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-API-Key: ' . $apiKey
    ],
    CURLOPT_POSTFIELDS => json_encode(['email' => 'user@example.com'])
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$result = json_decode($response, true);

if ($result['success']) {
    echo "Status: " . $result['data']['status'] . "\n";
    echo "Score: " . $result['data']['score'] . "\n";
    echo "Provider: " . $result['data']['meta']['provider'] . "\n";
} else {
    echo "Error: " . $result['error']['message'] . "\n";
}

Error Responses

Invalid Email Format

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format"
  }
}

Missing Email

{
  "success": false,
  "error": {
    "code": "REQUEST_ERROR",
    "message": "Email is required"
  }
}

Insufficient Credits

{
  "statusCode": 402,
  "code": "INSUFFICIENT_CREDITS",
  "error": "Payment Required",
  "message": "Insufficient credits"
}