Everything you need to know about CleanMail email verification API.
Features
What does the verification check?
Our API checks:
- Syntax validation
- MX record existence
- SMTP connection and mailbox existence
- Disposable email detection
- Role account detection (info@, support@, etc.)
- Spam trap detection
- Greylist detection
- Free provider detection (Gmail, Yahoo, etc.)
What are webhooks?
Webhooks let you receive verification results asynchronously. When you submit a verification with a webhookUrl, we'll POST the result to your URL when processing completes. This is perfect for high-volume applications.
What is greylist detection?
Greylisting is a temporary rejection technique where mail servers temporarily refuse emails from unknown senders. When CleanMail encounters a greylisted server, the email may time out during verification. The isGreylisted field in our API response indicates if this occurred — the email address itself may be valid, but verification couldn't complete due to server behavior.
Should I block greylisted emails?
Not necessarily. Greylisting is a normal server behavior used to combat spam — many legitimate mail servers use it. We recommend treating greylisted emails as risky rather than invalid. The recipient's email address is likely valid, but the temporary rejection means you may want to retry verification later or proceed with caution in your email campaigns.
What's the difference between sync and async verification?
Sync: You wait for the result (typically 2-5 seconds). Best for low-volume use.
Async (Webhooks): You get a request ID immediately, then receive results at your webhook URL. Best for high-volume or real-time applications.
What risk levels mean
- Low: Safe to email, deliverable mailbox
- Medium: Some risk signals detected
- High: Spam trap, known bounces, or suspicious patterns
What is batch verification?
Batch verification lets you upload a CSV file with up to 5,000 email addresses and process them all at once. Results include deliverability status, risk level, spam trap detection, disposable detection, role account detection, DMARC/SPF records, and more. Results are sent to your email and available for download.
How do I use batch verification?
Go to the
Batch page, upload a CSV file with one email per line, and click Start Processing. You can monitor progress in real-time and cancel the job at any time. When complete, you'll receive an email with results and can download the CSV.
What CSV format is required for batch upload?
Create a CSV file with a single column containing email addresses, one per line. No headers needed. Example:
user@example.com
john.doe@company.com
sales@business.org
Maximum 5,000 emails per upload. Supports .csv files only.
What does the batch results CSV contain?
The batch results include 16 columns:
- email - The email address
- deliverable - true/false
- reason - Why it failed or succeeded
- risk_level - low/medium/high
- is_spamtrap - Spam trap detected
- is_disposable - Disposable email detected
- is_role_account - Role account (info@, support@, etc.)
- is_free_provider - Gmail, Yahoo, etc.
- is_catchall - Catch-all domain
- has_dmarc - DMARC policy 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 found
- risk_score - 0-100 risk score
Can I cancel a batch job?
Yes! While a batch job is processing, you can click the "Cancel" button to stop it. Partial results will be saved and available for download.
Technical
What's the API response time?
Most verifications complete in 2-5 seconds. Complex cases may take up to 10 seconds. Use webhooks for better UX in high-volume scenarios.
Is the API HTTPS only?
Yes, all API requests must use HTTPS. HTTP requests will be rejected.
What response format does the API return?
JSON responses with camelCase fields:
{
"email": "user@example.com",
"valid": true,
"reason": "deliverable",
"risk": "low",
"mxFound": true,
"delivery": "deliverable"
}
Why does CleanMail not offer breach detection?
Breach detection services like HaveIBeenPwned charge per query, which adds significant cost per verification. To keep our pricing competitive and offer higher verification limits at lower prices, we focus on delivering more email verifications for your dollar rather than adding premium features that increase costs for all users.
Can I test without an API key?
Yes! Use the demo endpoint: POST /api/demo/verify (no auth required). Limited to 10 requests per minute.