Mailboxlayer offers a simple REST-based JSON API enabling you to thoroughly check and verify email addresses right at the point of entry into your system.
In addition to checking the syntax, the actual existence of an email address using MX-Records and the Simple Mail Transfer Protocol (SMTP), and detecting whether or not the requested mailbox is configured to catch all incoming mail traffic, the mailboxlayer API is linked to a number of regularly updated databases containing all available email providers, which simplifies the separation of disposable (e.g. "mailinator") and free email addresses (e.g. "gmail", "yahoo") from individual domains.
Combined with typo checks, did-you-mean suggestions and a numeric score reflecting the quality of each email address, these structures will make it simple to automatically filter "real" customers from abusers and increase response and success rates of your email campaigns.
After signing up, every user is assigned a personal API Access Key - a unique "password" used to gain access to the API's data and features.
To authenticate with the mailboxlayer API, simply attach your access_key to the base endpoint URL:
http://apilayer.net/api/bulk_check?access_key=YOUR_ACCESS_KEY
Since all verification tools are returned by the same (and only) API endpoint, making an email validation request to the mailboxlayer API is incredibly simple.
Most basic API request:
Take a look at the following API request URL: (If you would like to try it yourself, get a Free Plan and don't forget to attach your Access Key to the URL)
https://apilayer.net/api/check ? access_key = YOUR_ACCESS_KEY & email = [email protected]
As you can see, in addition to the access_key parameter, there is only one required parameter (email) to start verifying email addresses.
Optional parameters:
smtp active by default. Set to "0" if you
don't want the API to perform SMTP checks
format set to "1" in order to request prettified
JSON result set (use only for debugging!)
callback append your preferred JSONP callback function
name. (See "JSONP Callbacks" section)
All mailboxlayer validation data is returned in universal and lightweight JSON format. Find below a standard API result set:
{
"email": "[email protected]",
"did_you_mean": "",
"user": "support",
"domain": "apilayer.net",
"format_valid": true,
"mx_found": true,
"smtp_check": true,
"catch_all": false,
"role": true,
"disposable": false,
"free": false,
"score": 0.8
}
API response objects:
Each API response consists of 10 different response objects:
| Object | Description |
|---|---|
| "email" | Contains the exact email address requested |
| "did_you_mean" | Contains a did-you-mean suggestion in case a potential typo has been detected. |
| "user" | Returns the local part of the request email address. (e.g. "paul" in "[email protected]") |
| "domain" | Returns the domain of the requested email address. (e.g. "company.com" in "[email protected]") |
| "format_valid" | Returns true or false depending on whether or not the general syntax of the requested email address is valid. |
| "mx_found" | Returns true or false depending on whether or not MX-Records for the requested domain could be found. |
| "smtp_check" | Returns true or false depending on whether or not the SMTP check of the requested email address succeeded. |
| "catch_all" | Returns true or false depending on whether or not the requested email address is found to be part of a catch-all mailbox. |
| "role" | Returns true or false depending on whether or not the requested email address is a role email address. (e.g. "[email protected]", "[email protected]") |
| "disposable" | Returns true or false depending on whether or not the requested email address is a disposable email address. (e.g. "[email protected]") |
| "free" | Returns true or false depending on whether or not the requested email address is a free email address. (e.g. "[email protected]", "[email protected]") |
| "score" | Returns a numeric score between 0 and 1 reflecting the quality and deliverability of the requested email address. |
The mailboxlayer API also offers the ability to request email checks for multiple email addresses at the same time. In order to process email addresses in bulk, simply append multiple comma-separated email addresses to the API's base URL.
https://apilayer.net/api/check
? access_key = YOUR_ACCESS_KEY
& emails = [email protected], [email protected],
[email protected], ...
The Bulk email check endpoint is available wiyh the Professional Plus plan, where you can search up to 25 email addresses, and with the Enterprise Plus plan where you can search up to 100 email addresses.
The API response has the same structure as described above, where an object is returned for every email address in the request.
All Customers may establish a secure connection (industry-standard SSL) to the mailboxlayer API and all data provided by and accessible through it.
To connect securely, simply attach an s to the HTTP Protocol. (resulting in https://)
Requests to the API are rate limited based on your current subscription plan:
| Subscription Plan | Rate Limit |
|---|---|
| Free | 300 Requests / Minute |
| Basic | 300 Requests / Minute |
| Professional | 300 Requests / Minute |
| Enterprise | 600 Requests / Minute |
Important: In order to ensure maximum API performance, we recommend all users to limit their usage to a maximum of 5 API requests per second.
If your rate limit for a given minute has been exceeded, the API will return an error carrying the type rate_limit_reached. This error is listed in the API Error Codes section below.
If your query fails, the mailboxlayer API will return a 3-digit error-code, an internal error type and a plain text "info" object containing suggestions for the user.
Find below an example error - triggered when the user did not provide an email address to validate:
{
"success": false,
"error": {
"code": 210,
"type": "no_email_address_supplied",
"info": "Please specify an email address. [Example: [email protected]]"
}
}
| Type | Message | Description |
|---|---|---|
| 404 | "404_not_found" | User requested a resource which does not exist. |
| 101 | "missing_access_key" | User did not supply an Access Key. |
| 101 | "invalid_access_key" | User entered an invalid Access Key. |
| 103 | "invalid_api_function" | User requested a non-existent API Function. |
| 104 | "usage_limit_reached" | User has reached or exceeded his subscription plan's monthly API Request Allowance. |
| 210 | "no_email_address_supplied" | User did not provide an email address. |
| 106 | "rate_limit_reached" | User has exceeded the maximum allowed rate limitation and is referred to the "Rate Limits" section of the API Documentation. |
| 102 | "inactive_user" | The user's account is not active. User will be prompted to get in touch with Customer Support. |
| 310 | "catch_all_access_restricted" | The user's current subscription plan does not support catch-all detection. |
| 999 | "timeout" | An unexpected timeout issue occurred. |
The mailboxlayer API also supports JSONP Callbacks. To use this feature, simply attach:
callback = CALLBACK_FUNCTION
to any API Endpoint, and the result set will be returned as the callback function you specified.
Example query:
http://apilayer.net/api/validate?callback=CALLBACK_FUNCTION
Not sure about what JSONP does? Here's a helpful Stack Overflow thread.
Example response:
CALLBACK_FUNCTION ({
{
"email": "[email protected]",
"did_you_mean": "",
"user": "support",
"domain": "apilayer.net",
"format_valid": true,
"smtp_check": true,
"role": true,
"disposable": false,
"free": false,
"score": 0.8
}
})
Note: The API also supports Access-Control (CORS) headers.
In order to enhance readability the mailboxlayer API features a built-in JSON format function, which displays the API's Response in typically JSON-structured format.
To enable this function, simply attach format=1 to any valid API request URL:
http://apilayer.net/api/bulk_check
? access_key = YOUR_ACCESS_KEY
[...]
& format = 1
Please be aware that enabling format increases the API response's file size and might cause problems when trying to parse it. Therefore it should be used for debugging purposes only.
When requesting the verification of an email address the mailboxlayer API will first and foremost perform a standard email syntax check, hence, verify its compliance with regular expression rules, such as:
The format of email addresses is local-part@domain where the local-part may be up to 64 characters long and the domain name may have a maximum of 253 characters. The formal definitions are in RFC 5322 and RFC 5321 – with a more readable form given in the informational RFC 3696.
Local part:
Domain part:
The domain name part of an email address has to conform to strict guidelines: it must match the requirements for a hostname, consisting of letters, digits, hyphens and dots. In addition, the domain part may be an IP address literal, surrounded by square braces, although this is rarely seen except in email spam.
Example:
The API response's format_valid JSON object will return true or false depending on whether or not the email's syntax is found valid.
{
[...]
"format_valid": true,
[...]
}
Read more about the Email Address Syntax »
If a potential misspelling or typo in the domain part of the requested email address is detected, the mailboxlayer API will pose an alternative email suggestion within the API result set's did_you_mean object.
Example:
{
"email": "[email protected]",
"did_you_mean": "[email protected]",
[...]
}
Please note: The email address contained in the did_you_mean object solely serves as a suggestion and does not have any impact on other API response objects.
The mailboxlayer API verifies email addresses using the lookup of MX-Records and the use of SMTP, the Simple Mail Transfer Protocol, which is the very protocol we all use to move emails on and across networks.
Our system initiates the process of real-time email verification by detecting whether or not the requested domain is configured to receive email. This is where the API's MX-Records check comes into play. If MX-Records for the given domain are found, the API's mx_found response object will let you know.
Example:
{
[...]
"mx_found": true,
[...]
}
Next, the mail server assigned to the requested email address is contacted via SMTP. The resulting SMTP conversation represents the key factor that ultimately lets us know whether or not the email address provided actually exists.
Example:
The API response's smtp_check JSON object will return true or false depending on whether or not an SMTP check turned out successful.
{
[...]
"smtp_check": true,
[...]
}
Turn off SMTP Check:
The mailboxlayer SMTP Check feature takes up around 75% of the API's entire response time. If you would like to skip SMTP and speed up the API response, you may turn it off by setting the API's smtp parameter to 0.
https://apilayer.net/api/check ? access_key = YOUR_ACCESS_KEY & email = [email protected] & smtp = 0
Please note: If the API's smtp parameter is inactive, both the mx_found and the smtp JSON response objects will return null.
A side note about SMTP:
Although the process of sending emails may seem as simple as pushing a button to the end user, there is a rather big amount of data being pushed back and forth in the course of getting an email from one server to another. Email servers often tend to act in very unpredictable ways and create problems out of nowhere, this is one reason why more and more businesses have been choosing to use an email verification service like the mailboxlayer API.
The mailboxlayer API's real-time verification process does not end with one SMTP check. Since many email servers out there are configured to catch (receive) all incoming mail traffic, regardless of the requested email adress's local part, a catch-all detection functionality has been implemented.
Due to it's heavy impact on the API's response time, this functionality is inactive by default. However, you may turn on catch-all detection simply by appending the API's catch_all parameter to the request URL and setting it to 1.
Example:
https://apilayer.net/api/check ? access_key = YOUR_ACCESS_KEY & email = [email protected] & catch_all = 1
Example:
The API response's catch_all JSON object will return true or false depending on whether or not the requested email address is found to be part of a catch-all mailbox.
{
[...]
"catch_all": true,
[...]
}
Please note: If the API's catch_all parameter is inactive, the respective catch_all JSON response object will return null.
Another part of mailboxlayer email verification is the process of detecting whether or not the requested email address is a role email address. A role email is an address that is typically pointing at a function (e.g. "support", "postmaster") instead of an individual or name.
This type of email address may in some cases be unwelcome when sending email campaigns, as open rates tend to be very low.
Example:
The API response's role JSON object will return true or false depending on whether or not the requested email is a role address.
{
[...]
"role": true,
[...]
}
The mailboxlayer API is hooked up to a daily updated database containing all available email providers, which means it is capable of identifying free email services like Gmail and Yahoo!.
Depending on whether or not the requested email address is found to be using a free service the API response's free JSON object will return true or false.
Example:
{
[...]
"free": true,
[...]
}
Although it is most usual to include free email addresses in your list of recipients, for certain types of email campaigns it might make sense to sort them out and only send to email addresses using an individual domain.
The API will also return a disposable JSON object containing true or false depending on whether or not the requested email address is found to be using a disposable email provider like mailinator.com or trashmail.com.
Example:
{
[...]
"disposable": true,
[...]
}
Disposable Email Services
A disposable email service lets users anonymously create a temporary email addresses that expires after a certain time period and is often used only once for purposes like activating accounts or receiving passwords. Many of these email providers do not require the user to sign up, which makes the inbox of these one-time email addresses publicly visible. We highly advise against including these types of email addresses in your list of recipients.
To round off the mailboxlayer validation & verification process the API will return a numeric Quality Score ranging between 0 (Bad) and 1 (Good) reflecting the quality and deliverablity of the requested email address.
Example:
{
[...]
"score": 0.8
}
This Quality Score is calculated for each requested email address based on an algorithm that grows smarter which each email address validated and is focused on evaluating three main factors:
Since the validity of the numeric quality score strongly depends on which type of email approach you are making, it is not possible to define clear lines between "worth sending to" and "not worth sending to". However, here are some guidelines that make sense ot us:
For transactional email:
| Score | Quality |
|---|---|
| 1.00-0.65 | Good |
| 0.64-0.33 | Medium |
| 0.32-0.00 | Bad |
For marketing email:
| Score | Quality |
|---|---|
| 1.00-0.80 | Good |
| 0.79-0.49 | Medium |
| 0.48-0.00 | Bad |
Please note: The Quality Score solely serves as an indicator and should not be the only decisive factor when determing whether ot not to send to an email address.
Find below a simple way of using PHP (cURL) to verify an email address:
// set API Access Key $access_key = 'YOUR_ACCESS_KEY'; // set email address $email_address = '[email protected]'; // Initialize CURL: $ch = curl_init('http://apilayer.net/api/bulk_check?access_key='.$access_key.'&email='.$email_address.''); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // Store the data: $json = curl_exec($ch); curl_close($ch); // Decode JSON response: $validationResult = json_decode($json, true); // Access and use your preferred validation result objects $validationResult['format_valid']; $validationResult['smtp_check']; $validationResult['score'];
Find below a simple way of using jQuery.ajax to verify an email address:
// set endpoint and your access key var access_key = 'YOUR_ACCESS_KEY'; var email_address = '[email protected]'; // verify email address via AJAX call $.ajax({ url: 'http://apilayer.net/api/bulk_check?access_key=' + access_key + '&email=' + email_address, dataType: 'jsonp', success: function(json) { // Access and use your preferred validation result objects console.log(json.format_valid); console.log(json.smtp_check); console.log(json.score); } });
Please note: In this example, the use of JSONP is entirely optional.
Ensuring our customers achieve success is paramount to what we do at APILayer. For this reason, we will be rolling out our Business Continuity plan guaranteeing your end users will never see a drop in coverage. Every plan has a certain amount of API calls that you can make in the given month. However, we would never want to cut your traffic or impact user experience negatively for your website or application in case you get more traffic.
An overage occurs when you go over a quota for your API plan. When you reach your API calls limit, we will charge you a small amount for each new API call so we can make sure there will be no disruption in the service we provide to you and your website or application can continue running smoothly.
Prices for additional API calls will vary based on your plan. See table below for prices per call and example of an overage billing.
| Plan Name | Monthly Price | Number of Calls | Overage Price per call | Overage | Total price |
|---|---|---|---|---|---|
| Basic | $14.99 | 5,000 | 0.004497 | 1000 | $19.49 |
| Professional Plus | $74.99 | 50,000 | 0.0022497 | 10,000 | $97.49 |
| Enterprise Plus | $249.99 | 250,000 | 0.00149994 | 50,000 | $324.99 |
Overage fees allow developers to continue using an API once a quota limit is reached and give them time to upgrade their plan based on projected future use while ensuring API providers get paid for higher usage.
When you are close to reaching your API calls limit for the month, you will receive an automatic notification (at 75%, 90% and 100% of your monthly quota). However, it is your responsibility to review and monitor for the plan’s usage limitations. You are required to keep track of your quota usage to prevent overages. You can do this by tracking the number of API calls you make and checking the dashboard for up-to-date usage statistics.
You will be charged for your monthly subscription plan, plus any overage fees applied. Your credit card will be billed after the billing period has ended.
In this case, there will be no change to your monthly invoice. Only billing cycles that incur overages will see any difference in monthly charges. The Business Continuity plan is an insurance plan to be used only if needed and guarantees your end users never see a drop in coverage from you.
If your site consistently surpasses the set limits each month, you may face additional charges for the excess usage. Nevertheless, as your monthly usage reaches a certain threshold, it becomes more practical to consider upgrading to the next plan. By doing so, you ensure a smoother and more accommodating experience for your growing customer base.
You can easily upgrade your plan by going to your Dashboard and selecting the new plan that would be more suitable for your business needs. Additionally, you may contact your Account Manager to discuss a custom plan if you expect a continuous increase in usage.
Upgrade your APIlayer subscription with our exclusive Platinum Support, an exceptional offering designed to enhance your business’ API management journey. With Platinum Support, you gain access to a host of premium features that take your support experience to a whole new level.
| Standard Support | Platinum Support | |
|---|---|---|
| General review on the issue |  |
|
| Access to knowledge base articles | |
|
| Email support communication | |
|
| Regular products updates and fixes | |
|
| Dedicated account team |  |
|
| Priority Email Support with unlimited communication | |
|
| Priority bug and review updates | |
|
| Option for quarterly briefing call with product Management | |
|
| Features requests as priority roadmap input into product | |
|
Priority Email Support: Experience unrivaled responsiveness with our priority email support. Rest assured that your inquiries receive top-priority attention, ensuring swift resolutions to any issues.
Unlimited Communication: Communication is key, and with Platinum Support, you enjoy unlimited access to our support team. No matter how complex your challenges are, our experts are here to assist you every step of the way.
Priority Bug Review and Fixes: Bugs can be a headache, but not with Platinum Support. Benefit from accelerated bug review and fixes, minimizing disruptions and maximizing your API performance.
Dedicated Account Team: We understand the value of personalized attention. That's why Platinum Support grants you a dedicated account team, ready to cater to your specific needs and provide tailored solutions.
Quarterly Briefing Call with Product Team: Stay in the loop with the latest updates and insights from our Product team. Engage in a quarterly briefing call to discuss new features, enhancements, and upcoming developments.
Priority Roadmap Input: Your input matters! As a Platinum Support subscriber, your feature requests receive top priority, shaping our product roadmap to align with your evolving requirements.
Don't settle for the standard when you can experience the exceptional. Upgrade to Platinum Support today and supercharge your APIlayer experience!
|
|