📚 CleanMail API Documentation

Complete guide to integrating CleanMail's email verification API into your application.

🔐 Authentication

All API requests require authentication using your API key via the X-API-Key header.

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

✅ Verify Email

Verify an email address to check if it's valid, deliverable, and not a spam trap or disposable.

Request Body

Example Request

{
  "email": "user@example.com",
  "webhookUrl": "https://yourapp.com/webhooks/cleanmail"
}

Example Response

{
  "email": "user@example.com",
  "valid": true,
  "reason": "deliverable",
  "risk": "low",
  "isDisposable": false,
  "isRoleAccount": false,
  "isFreeProvider": false,

  "isSpamTrap": false,
  "isGreylisted": false,
  "mxFound": true,
  "delivery": "deliverable",
  "requestId": "req_abc123"
}

Response Fields

🔔 Webhooks

Receive real-time notifications when email verifications complete.

How It Works

1. Submit verification with your webhook URL:
POST /api/verify
{
  "email": "user@example.com",
  "webhookUrl": "https://yourapp.com/webhooks/cleanmail"
}

2. Receive result at your webhook:
POST https://yourapp.com/webhooks/cleanmail
{
  "requestId": "req_abc123",
  "email": "user@example.com",
  "valid": true,
  "reason": "deliverable",
  ...
}

Webhook Payload

{
  "requestId": "req_abc123",
  "email": "user@example.com",
  "valid": true,
  "reason": "deliverable",
  "risk": "low",
  "isDisposable": false,
  "isRoleAccount": false,
  "isFreeProvider": false,

  "isSpamTrap": false,
  "isGreylisted": false,
  "mxFound": true,
  "delivery": "deliverable",
  "verifiedAt": "2026-04-20T12:00:00Z"
}

📋 Batch Verification

Process up to 5,000 email addresses at once with batch verification. Upload a CSV, monitor progress, and receive results via email.

Upload Batch

Upload a CSV file with email addresses. Maximum 5,000 emails per upload.

curl -X POST https://cleanmail.dev/api/batch/upload \
  -H "X-API-Key: your_api_key" \
  -F "file=@emails.csv"

CSV Format

Create a CSV with a single column of email addresses, one per line:

user@example.com
john.doe@company.com
sales@business.org

Check Batch Status

curl https://cleanmail.dev/api/batch/status/your-job-id \
  -H "X-API-Key: your_api_key"

Response:

{
  "success": true,
  "jobId": "abc123",
  "status": "processing",
  "total": 500,
  "processed": 234,
  "valid": 45,
  "invalid": 189,
  "queued": 0
}

Get Batch History

Returns your recent batch jobs (last 20).

Download Results

curl "https://cleanmail.dev/api/batch/download/abc123?key=your_api_key"

Cancel Batch Job

curl -X POST https://cleanmail.dev/api/batch/cancel/abc123 \
  -H "X-API-Key: your_api_key"

Batch Results CSV

When complete, download the CSV with these columns:

Column	Description
email	The email address
deliverable	true/false - mailbox exists
reason	Why valid or invalid
risk_level	low/medium/high
is_spamtrap	Spam trap detected
is_disposable	Disposable email domain
is_role_account	Role account (info@, support@)
is_free_provider	Gmail, Yahoo, Outlook, etc.
is_catchall	Catch-all domain
has_dmarc	DMARC record present
dmarc_policy	none/quarantine/reject
has_spf	SPF record present
spf_strict	Strict SPF enforcement
domain_age_days	Age of domain in days
mx_record	MX server hostname
risk_score	0-100 risk score

🧪 Demo Endpoint

Try CleanMail without an API key! The demo endpoint is rate-limited but lets you test the service.

curl -X POST https://cleanmail.dev/api/demo/verify \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com"}'

❌ Error Codes

📦 Plans & Limits

View full pricing details →

💻 Code Examples

JavaScript / Node.js

const response = await fetch('https://cleanmail.dev/api/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your_api_key'
  },
  body: JSON.stringify({
    email: 'user@example.com',
    webhookUrl: 'https://yourapp.com/webhooks/cleanmail'
  })
});

const result = await response.json();
console.log(result);
// { valid: true, reason: 'deliverable', ... }

Python

import requests

response = requests.post(
    'https://cleanmail.dev/api/verify',
    headers={'X-API-Key': 'your_api_key'},
    json={'email': 'user@example.com'}
)

result = response.json()
print(result)

cURL

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

PHP

$ch = curl_init('https://cleanmail.dev/api/verify');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-API-Key: your_api_key'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'email' => 'user@example.com'
]));
$response = curl_exec($ch);
$result = json_decode($response, true);

📞 Need Help?

Contact us at CleanMail.service@gmail.com for technical support or sales inquiries.

Check our FAQ →