Quickstart

Validate your first email

From zero to a verified address in a few minutes — with the SDK for your stack or a plain HTTP call.

1. Get an API key

Create a free account (100 credits, no card) and create a key under API & AI clients in your dashboard. New keys can check single addresses and lists, and connect AI clients.

2. Note your organization ID

Every request runs in the context of an organization — your team. Your organization ID is your team ID, sent as the X-Organization-ID header. You'll find it in your dashboard.

3. Make your first call

With an official SDK:

php
// composer require bounceshift/laravel   (or bounceshift/bounceshift-php)
$result = BounceShift::validate('jane@gmail.com');

$result->status->value;   // 'valid', 'catch_all', 'unknown', ...
$result->isSafeToSend();  // true for 'valid' or 'catch_all'
typescript
// npm install @bounceshift/sdk
const result = await bounceshift.validate('jane@gmail.com');

result.status;         // 'valid' | 'catch_all' | 'unknown' | ...
isSafeToSend(result);  // true for 'valid' or 'catch_all'

Or straight over HTTP:

cURL
curl -X POST https://api.bounceshift.com/v1/validate/single \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Organization-ID: YOUR_ORG_ID" \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@gmail.com"}'

4. Read the result

Every validation returns a status, a 0–100 confidence score, granular flags, and a sub_status:

json
{
    "email": "jane@gmail.com",
    "status": "valid",
    "sub_status": "smtp_verified",
    "did_you_mean": null,
    "recommendation": "deliverable",
    "send_priority": null,
    "quality_score": 80,
    "explanation": "The mailbox accepted mail during a live SMTP check — it exists and can receive email.",
    "confidence": 80,
    "mx_found": true,
    "smtp_valid": true,
    "is_disposable": false,
    "is_catch_all": false,
    "is_role_account": false,
    "from_cache": false,
    "credits_used": 1,
    "result": {
        "reason": "smtp_verified"
    }
}

The headline field is status. It's safe to send when the status is valid or catch_all. See the full status & error-code reference for what every value means — and note that an unknown result means "we couldn't confirm," not "invalid," so don't discard those addresses.

Next steps

Learn

Understand the engine

Check your list before you send it

Upload a CSV and get back the addresses that are safe to send. 100 free credits to start, no card, and no charge for the ones we can't verify.