API Documentation

Complete reference for the BounceHalt Email Verification API. Verify any email address in real-time with a single API call. Multi-layered checks including syntax, DNS, SMTP, and deliverability analysis.

Authentication

All API requests require authentication via the x-api-key header. Include your API key in every request:

x-api-key: your_api_key_here

API keys are available from your dashboard after signing up. Keep your API key confidential — do not expose it in client-side code or public repositories.

Base URL

All endpoints are served over HTTPS. HTTP requests will be redirected to HTTPS.

Check Email

Verify a single email address. Returns comprehensive deliverability information including syntax validation, MX records, SMTP verification, and risk assessment.

curl -X POST https://api.bouncehalt.com/v1/check-email \
  -H "Content-Type: application/json" \
  -H "x-api-key: your_api_key_here" \
  -d '{
    "to_email": "jane@example.com"
  }'

{
  "input": "jane@example.com",
  "is_reachable": "safe",
  "misc": {
    "is_disposable": false,
    "is_role_account": false,
    "gravatar_url": null,
    "haveibeenpwned": null
  },
  "mx": {
    "accepts_mail": true,
    "records": [
      "alt1.aspmx.l.google.com.",
      "aspmx.l.google.com."
    ]
  },
  "smtp": {
    "can_connect_smtp": true,
    "has_full_inbox": false,
    "is_catch_all": false,
    "is_deliverable": true,
    "is_disabled": false
  },
  "syntax": {
    "address": "jane@example.com",
    "domain": "example.com",
    "is_valid_syntax": true,
    "username": "jane"
  }
}

Verifying Lists

Verify multiple email addresses by calling the check-email endpoint once for each address in your list. Iterate over your addresses and send one request per email, respecting your plan's rate limits.

const emails = ['alice@example.com', 'bob@test.com', 'carol@gmail.com'];

for (const email of emails) {
  const res = await fetch('https://api.bouncehalt.com/v1/check-email', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': process.env.BOUNCEHALT_API_KEY,
    },
    body: JSON.stringify({ to_email: email }),
  });
  const result = await res.json();
  console.log(email, result.is_reachable);
}

API Version

The current API version is v1. All endpoints are under the /v1/ path prefix. We will communicate breaking changes in advance and maintain backward compatibility within major versions.

Response Fields

The verification response contains detailed information across several categories:

Top-level Fields

syntax

mx

smtp

misc

Reachability Values

The is_reachable field returns one of four values:

HTTP Status Codes

Rate Limits

Rate limits vary by plan:

When rate limited, the API returns a 429 status code with a Retry-After header indicating when to retry.

Quick Start Guide

Get started verifying emails in under 2 minutes:

1. Sign up — Create an account at bouncehalt.com
2. Get your API key — Find it in your dashboard under API Settings
3. Make your first request — Use the curl example above, replacing your_api_key_here with your actual key
4. Integrate — Add verification to your signup flows, CRM imports, or before importing lists into your email provider

Node.js Example

const response = await fetch('https://api.bouncehalt.com/v1/check-email', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': process.env.BOUNCEHALT_API_KEY,
  },
  body: JSON.stringify({ to_email: 'jane@example.com' }),
});
const result = await response.json();
console.log(result.is_reachable); // "safe", "risky", "invalid", or "unknown"

Python Example

import requests

response = requests.post(
    'https://api.bouncehalt.com/v1/check-email',
    headers={
        'Content-Type': 'application/json',
        'x-api-key': 'your_api_key_here',
    },
    json={'to_email': 'jane@example.com'},
)
result = response.json()
print(result['is_reachable'])  # "safe", "risky", "invalid", or "unknown"

Error Handling

When an error occurs during verification, the response will include error details in the relevant section. For example, an SMTP connection failure will appear in the smtp object:

{
  "smtp": {
    "can_connect_smtp": false,
    "error": {
      "type": "SmtpError",
      "message": "Connection timed out after 30 seconds"
    }
  }
}

Best practices for error handling:

• Always check the is_reachable field first for the overall verdict
• For unknown results, implement a retry with exponential backoff
• Log error details for debugging integration issues
• Set reasonable timeouts in your HTTP client (we recommend 30 seconds)

Need help with integration? Contact us at support@bouncehalt.com or check our contact page.