API Documentation

mailboxlayer API

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.


Specs & Overview

API Access Key & Authentication

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/check?access_key=YOUR_ACCESS_KEY  
                

Get your free API Access Key


Make an API Request

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 = support@apilayer.com
                

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)
                

API Response

All mailboxlayer validation data is returned in universal and lightweight JSON format. Find below a standard API result set:

{
  "email": "support@apilayer.com",
  "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 "paul@company.com")
"domain" Returns the domain of the requested email address. (e.g. "company.com" in "paul@company.com")
"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. "support@company.com", "postmaster@company.com")
"disposable" Returns true or false depending on whether or not the requested email address is a disposable email address. (e.g. "user123@mailinator.com")
"free" Returns true or false depending on whether or not the requested email address is a free email address. (e.g. "user123@gmail.com", "user123@yahoo.com")
"score" Returns a numeric score between 0 and 1 reflecting the quality and deliverability of the requested email address.


256-bit HTTPS Encryption
Free Basic Pro Enterprise

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://)


Rate Limits

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.


API Error Codes

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: support@apilayer.com]"    
  }
}
                


Common API errors:


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.
310 "catch_all_access_restricted" The user's current subscription plan does not support catch-all detection.
999 "timeout" An unexpected timeout issue occurred.

show all errors


JSONP Callbacks

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": "support@apilayer.com",
  "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.


JSON Formatting

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/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.


API Validation Tools

Syntax Check
Free Basic Pro Enterprise

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:

  • Uppercase and lowercase Latin letters (A–Z, a–z) (ASCII: 65–90, 97–122)
  • Digits 0 to 9 (ASCII: 48–57)
  • These special characters: # - _ ~ ! $ & ' ( ) * + , ; = : and percentile encoding i.e. %20
  • Character . (dot, period, full stop), ASCII 46, provided that it is not the first or last character, and provided also that it does not appear consecutively (e.g. John..Doe@example.com is not allowed).
  • [...]

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 »


Typo Check & Suggestions
Free Basic Pro Enterprise

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": "user@gnail.com",
  "did_you_mean": "user@gmail.com",
  [...]
}        
                

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.


Real-time Verification
Free Basic Pro Enterprise

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 = support@apilayer.com
    & 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.


Catch-all Detection
Basic Pro Enterprise

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 = support@apilayer.com
    & 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.


Role Check
Free Basic Pro Enterprise

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,
  [...]
}        
                

Free Provider Check
Free Basic Pro Enterprise

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.


Disposable Provider Check
Free Basic Pro Enterprise

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.


Quality Score
Free Basic Pro Enterprise

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:

  • Appearance: How close does the local or domain part of the email address get to the most valued and highest quality email addresses.

  • Deliverablity: Is the general email syntax valid. Does the SMTP check find the requested email address to actually exist.

  • Background: Is the requested email address associated with a free or disposable email provider. Does it point to a role.

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.


Code Examples

PHP (cURL)

Verify 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 = 'support@apilayer.com';

// Initialize CURL:
$ch = curl_init('http://apilayer.net/api/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'];
                

JavaScript (jQuery.ajax)

Verify email address:

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 = 'support@apilayer.com';

// verify email address via AJAX call
$.ajax({
    url: 'http://apilayer.net/api/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.