📚 CleanMail API Documentation

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

Table of Contents

Authentication Verify Email Endpoint Webhooks Demo Endpoint Error Codes Plans & Limits Code Examples

🔐 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"}'
💡 Finding your API Key: Sign in to your dashboard at cleanmail.dev/app.html to view your API key.

✅ Verify Email

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

POST /api/verify

Request Body

email required string - Email address to verify
webhookUrl string - Optional URL for async results

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,
  "isCatchall": false,
  "isSpamTrap": false,
  "mxFound": true,
  "delivery": "deliverable",
  "requestId": "req_abc123"
}

Response Fields

valid boolean - Overall validity
reason string - Reason for validity status
risk string - "low", "medium", or "high"
mxFound boolean - MX record exists
delivery string - "deliverable", "undeliverable", or "risky"

🔔 Webhooks

Receive real-time notifications when email verifications complete.

Why Use Webhooks?

Webhooks enable asynchronous processing. Submit verification requests and receive results at your callback URL when processing completes—perfect for high-volume applications.

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,
  "isCatchall": false,
  "isSpamTrap": false,
  "mxFound": true,
  "delivery": "deliverable",
  "verifiedAt": "2026-04-20T12:00:00Z"
}
💡 Best Practice: Respond to webhooks with 200 OK immediately, then process asynchronously to avoid timeouts.

🧪 Demo Endpoint

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

POST /api/demo/verify 
curl -X POST https://cleanmail.dev/api/demo/verify \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com"}'
⚠️ Limits: Demo endpoint is limited to 10 requests per minute. For production use, sign up for an API key.

❌ Error Codes

400 Bad Request - Missing or invalid email
401 Unauthorized - Invalid or missing API key
429 Rate Limited - Daily quota exceeded
500 Server Error - Try again later

📦 Plans & Limits

Free
$0
  • 100 verifications/day
  • Email support
  • Basic API access
Starter
$9/mo
  • 500 verifications/day
  • Webhooks
  • Priority support
Pro
$29/mo
  • 2,000 verifications/day
  • Webhooks
  • API access
Business
$79/mo
  • 5,000 verifications/day
  • Webhooks
  • Dedicated support

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 support@cleanmail.dev for technical support or sales inquiries.

Check our FAQ →