API Documentation

Integrate real-time email verification into your applications. Validate addresses at signup, checkout, or in bulk before campaigns.

Authentication

All API requests require an API key. Create one from your dashboard under the API Keys tab.

Pass your key in the X-Api-Key header:

curl -H "X-Api-Key: cv_your_key_here" \
  https://verify.cascade-mail.com/api/verify.php

You can also pass the key as a query parameter for simple testing:

GET /api/verify.php?email=test@example.com&api_key=cv_your_key_here

Base URL & Format

All endpoints accept and return JSON. Set Content-Type: application/json for POST requests.

Responses always include a success boolean and either a result object or an error string.

Rate Limits

Rate limits are based on your plan tier:

Each verification consumes 1 credit regardless of result. Credits never expire.

Verify Single Email

Verify a single email address and receive a comprehensive deliverability report.

curl -X POST https://verify.cascade-mail.com/api/verify.php \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: cv_your_key_here" \
  -d '{"email": "john.smith@example.com"}'

{
  "success": true,
  "result": {
    "email": "john.smith@example.com",
    "domain": "example.com",
    "valid_syntax": true,
    "mx_records": ["mx1.example.com", "mx2.example.com"],
    "deliverable": true,
    "status": "deliverable",
    "status_detail": "Email address is deliverable",
    "is_catchall": false,
    "score": 9,
    "score_factors": [
      "MX found (+2)",
      "Multiple MX (+0.5)",
      "SMTP connected (+1)",
      "EHLO accepted (+0.5)",
      "MAIL FROM accepted (+0.5)",
      "RCPT TO accepted (+3)",
      "SPF record (+0.5)",
      "DMARC record (+0.5)",
      "Website exists (+0.25)",
      "Real name pattern (+0.5)"
    ],
    "is_disposable": false,
    "is_role_account": false,
    "is_known_provider": false,
    "dns_health": {
      "has_spf": true,
      "has_dmarc": true,
      "has_a_record": true
    },
    "smtp_check": {
      "mx_host": "mx1.example.com",
      "connected": true,
      "helo_ok": true,
      "mail_from_ok": true,
      "rcpt_to_ok": true,
      "rcpt_to_code": 250,
      "rcpt_to_response": "250 2.1.5 OK"
    },
    "server_policy": null,
    "credits_remaining": 1847
  }
}

Status Codes

The status field in every response indicates the verification verdict:

Deliverability Score

Every verified email receives a score from 1 to 10 based on multiple signals. Use this score to make send/don't-send decisions, especially for unknown status results.

Score Factors

The score_factors array shows exactly which signals contributed to the score:

Server Policy Detection

When a server rejects verification but the rejection is ambiguous, we probe with a fake address to determine the server's policy:

Bulk Verification

For verifying large lists, use the CSV upload through the dashboard. The bulk flow is a three-step process:

1. Upload — POST a CSV file. The API parses emails and returns a batch_id.
2. Process — Confirm processing with the batch_id. Each email is verified and credits deducted.
3. Download — Retrieve results as a CSV with status, score, and flags for each address.

curl -X POST https://verify.cascade-mail.com/api/bulk.php?action=upload \
  -F "csv=@emails.csv"

{
  "success": true,
  "batch_id": "a1b2c3d4-e5f6-...",
  "emails_found": 500,
  "credits_remaining": 1500
}

curl -X POST https://verify.cascade-mail.com/api/bulk.php?action=process \
  -H "Content-Type: application/json" \
  -d '{"batch_id": "a1b2c3d4-e5f6-..."}'

Quick Start

cURL

curl -X POST https://verify.cascade-mail.com/api/verify.php \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: cv_your_key_here" \
  -d '{"email": "user@example.com"}'

PHP

$ch = curl_init('https://verify.cascade-mail.com/api/verify.php');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json',
        'X-Api-Key: cv_your_key_here',
    ],
    CURLOPT_POSTFIELDS => json_encode(['email' => 'user@example.com']),
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

if ($result['result']['score'] >= 7) {
    echo "Safe to send!";
}

Python

import requests

response = requests.post(
    'https://verify.cascade-mail.com/api/verify.php',
    json={'email': 'user@example.com'},
    headers={'X-Api-Key': 'cv_your_key_here'}
)
data = response.json()
result = data['result']

print(f"{result['email']}: {result['status']} (score: {result['score']}/10)")

JavaScript

const res = await fetch('https://verify.cascade-mail.com/api/verify.php', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Api-Key': 'cv_your_key_here',
  },
  body: JSON.stringify({ email: 'user@example.com' }),
});
const { result } = await res.json();
console.log(`${result.email}: ${result.status} (${result.score}/10)`);

CSV Upload Guide

The bulk verifier accepts CSV or TXT files. It automatically detects the email column — just make sure at least one column contains valid email addresses.

Supported formats:

• Single column: one email per line
• Multi-column: header row with a column named email, email_address, or e-mail
• Mixed data: the parser finds the first valid email in each row

Error Handling

All errors return a JSON object with an error field:

{
  "error": "No credits remaining. Please upgrade your plan.",
  "credits_remaining": 0
}

Plans & Credits

Every verification consumes 1 credit. Credits never expire. When you run out, you'll receive a 402 response. Upgrade from your dashboard account tab.