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 Rapid API account (available for free).
- An API key. You can obtain this from your Rapid account dashboard once registered.
- Basic understanding of HTTP requests.
Free Plan
On Rapid, 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 endpoints under this base URL.
Authentication
To authenticate requests, include your API key in the X-RapidAPI-Key header:
Example:
curl -X GET "https://mailcheck.p.rapidapi.com/?email=example@mail.com" \
-H "X-RapidAPI-Key: YOUR_API_KEY"
Making Your First Request
Verify an Email Address
To check if an email address is disposable, make a GET request to / with the email address as a query parameter:
Endpoint:
Example Response:
{
"valid": true,
"block": true,
"disposable": true,
"domain": "temp-mail.org",
"text": "Disposable / temporary domain",
"reason": "Heuristics x6",
"risk": 99,
"mx_host": "mx.yandex.net",
"possible_typo": [],
"mx_ip": "77.88.21.249",
"mx_info": "Using MX pointer mx.yandex.net from DNS with priority: 10",
"last_changed_at": "2020-04-18T22:05:24+02:00"
}
The response will include information on whether the email is disposable, its domain, and if it is a valid format.
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 you 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 Rapid, and sign up for the API.
- 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.