API and Authentication
Check-Mail is an advanced API for detecting and blocking disposable and temporary email addresses. This guide will help you set up and start using the Check-Mail API quickly and effectively.
Prerequisites
Before you begin, ensure you have the following:
- An active Check-Mail account (available for free).
- An API key. You can obtain this from your account dashboard once registered.
- Basic understanding of HTTP requests.
Free Plan
You can sign up for a free version of the API, which allows for 1000 lookups per month.
API Endpoint
The base URL for the Check-Mail API is:
All API requests will be made to this endpoint using POST.
Authentication
To authenticate requests, include your API key in the Authorization header as a Bearer token:
Example:
curl -X POST "https://api.check-mail.org/v2/" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d "email=example@mail.com"
Making Your First Request
Verify an Email Address
To check if an email address is disposable, make a POST request to the endpoint with the email address as form data:
Example:
curl -X POST "https://api.check-mail.org/v2/" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d "email=mail@temp-mail.org"
You can also submit just a domain instead of a full email address (useful for GDPR compliance):
curl -X POST "https://api.check-mail.org/v2/" \
-H "Authorization: Bearer YOUR_API_KEY" \
-d "domain=temp-mail.org"
Example Response:
{
"valid": true,
"block": true,
"domain": "temp-mail.org",
"base_domain": "temp-mail.org",
"text": "Disposable / temporary domain",
"reason": "Heuristics x5",
"risk": 99,
"is_disposable": true,
"is_email_forwarder": false,
"is_public_free": false,
"is_public_premium": false,
"is_business_provider": false,
"is_isp_email": false,
"is_email_api": false,
"is_web_hosting_email": false,
"is_self_hosted": false,
"is_parked": false,
"is_role_based_email": false,
"mx_host": "amir.mx.cloudflare.net",
"mx_ip": "162.159.205.13",
"mx_info": "Using MX pointer amir.mx.cloudflare.net from DNS with priority: 15",
"mx_fallback": false,
"mx_hosts": [
"amir.mx.cloudflare.net"
],
"mx_ips": [
"162.159.205.13"
],
"mx_priorities": {
"amir.mx.cloudflare.net": 15,
"isaac.mx.cloudflare.net": 93,
"linda.mx.cloudflare.net": 30
},
"email_provider": "Cloudflare Email Routing",
"disposable_provider": "temp-mail.org",
"possible_typo": [],
"domain_age_days": 5074,
"domain_created_at": "2012-05-05T00:00:00+00:00",
"block_status_changed_at": "2020-04-18T22:05:24+00:00"
}
The response will include information on whether the email is disposable, its domain, risk score, and much more.
Response Codes
- 200 OK: The request was successful.
- 401 Unauthorized: Your API key is incorrect or missing.
- 429 Too Many Requests: You have exceeded the monthly limits of your current plan (1000 for free per month).
Rate Limits
Your current plan's rate limit details can be found in your account dashboard. Free accounts can make 1000 requests per month.
If you exceed the rate limit, you will receive a 429 Too Many Requests status code.
Requests remaining
In your HTTP response, the header "x-ratelimit-requests-remaining", will contain the number of requests you have remaining for this current period (30 days).
Error Handling
The API returns the standard HTTP status codes to indicate the success or failure of your requests. Always check the response code to handle errors gracefully in your application.
Example of Error Response:
Next Steps
- Make sure you have an account at app.check-mail.org.
- Try out some examples from the Examples and Tutorials section to better understand how to use the API.
- Read the Best Practices guide to optimize your integration.