Getting Started
Specification and Overview
API Access Key & Authentication
After signing up, every user is assigned a personal API Access Key—a unique "password" used to access the API's data and features.
To authenticate with the Mailboxlayer API, simply attach your access_key to the base endpoint URL:
Get 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)
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:
API Response
All Mailboxlayer validation data is returned in universal and lightweight JSON format. Find below a standard API result set:
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. |
Bulk Email Address Check
The Mailboxlayer API also allows you to request email checks for multiple email addresses at once. To process email addresses in bulk, simply append multiple comma-separated email addresses to the API's base URL.
The Bulk email check endpoint is available with 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 described above, with an object returned for each email address in the request.
256-bit HTTPS Encryption
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:
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. |
| 211 | "format_not_valid" | User has provided an email address with an invalid format. |
| 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. |
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:
Not sure about what JSONP does? Here's a helpful Stack Overflow thread.
Example response:
Note: The API also supports Access-Control (CORS) headers.
JSON Formatting
To enhance readability, the Mailboxlayer API includes a built-in JSON formatter that displays the API's Response in a typical JSON format.
To enable this function, simply attach format=1 to any valid API request URL:
Please be aware that enabling the format increases the API response's file size and might cause problems when parsing it. Therefore, it should be used only for debugging purposes.