The V3 API is our latest API release. It requires a license key or an authorised domain. Should you require our old documentation for any reason please navigate to our API Documentation V1. This quick start guide has been designed to get you up and running with our real-time email verification API solution as fast as possible. Please follow the steps below in sequence: Create Account Create your account by clicking here. Login Login to your customer portal to retrieve your API License Key. Try it Insert your license key into the following URL: API access using key The value for [FORMAT] below can be specified as either JSON, JSONP or XML. It is not case sensitive. https://api.emailverifyapi.com/v3/lookups/[FORMAT]?email=[EMAIL]&key=[YOUR_API_KEY] Access where your domain has been whitelisted https://api.emailverifyapi.com/v3/lookups/[FORMAT]?email=[EMAIL]


The URL to pass to the API is: https://api.emailverifyapi.com/v3/lookups/[FORMAT]?email=[EMAIL]&key=[YOUR_API_KEY]
ParameterValueMandatory or Optional
formatjson, jsonp or xmlMandatory
emailthe email address to be validatedMandatory
keyyour unique API keyMandatory unless your domain has been whitelisted
correct0 or 1Optional - 1 enables the typo correction feature
Printable ASCII Special Characters When passing special characters as part of an email address, you must encode them as ASCII codes as per the table at https://ascii.cl/. Examples:
# should be encoded as %23
* should be encoded as %2A
& should be encoded as %26
API Credits Exhausted Should your API credits be exhausted, you will receive the message “Rate limit exceeded – If you’d like a higher request volume please contact sales@emailchecker.comValidation Results The API V3 validation results are presented using a different set of fields to that of V1. As mentioned previously, the real-time API V3 has the ability to output the validation result in different formats – JSON, JSONP and XML. The responses in each format would appear as follows: JSON Format JSONP Format XML Format Click the “View Raw” link in the XML Format Gist above to see the full XML tree. The fields and values in the results are the same whether encoded as JSON, JSONP or XML. They are simply formatted in a different output for your preference of real-time API client.


The table below details the main API responses from the Email Checker V3 API.
ResponseReturn Code(s) or Value(s)Explanation
addressEmail addressValidates the email address that has been verified
usernameusernameThe username part of the email address before the @
domaindomain nameThe domain name part of the email address after the @
md5Hashmd5 hash valueA unique MD5 hash value computed from the email address
suggestionEmail addressA suggestion for emails with suspected typos
validFormattrue or falseWhether the email address was in a valid RFC format
deliverabletrue or falseIf we are able to deliver to the email address
fullInboxtrue or falseWhether the destination Inbox was full and therefore rejecting messages
hostExiststrue or falseIf the destination mail server exists
catchAlltrue or falseThe domain for the email address will accept any username part before the @, therefore it cannot be validated
gravatarfalse — Always return false at the momentIf there is a gravatar.com avatar configured for the email address
roleEmail addressThe email address is a default "role" - see next table below
disposabletrue or falseEmail is a known disposable, typically quick-turnaround addresses that are disposed of quickly
freetrue or falseEmail address is from a "free" provider such as hotmail, outlook, gmail
The “role” response will return if the email address includes any of the following: Two additional responses are possible from the API. In the event that a target mail server does not respond within our environment timeframe: This message appears when the target mail server either does not respond or takes too long to respond. These email addresses can be retried at a later time. In the event that the API license key is invalid: Special handling of Gmail/Googlemail addresses. Addresses with gmail.com or googlemail.com domain suffixes behave differently from “usual” email accounts. myemail@gmail.com is the same as my.email@gmail.com and m.y.e.m.a.i.l@gmail.com. Therefore, whatever address is submitted, you may receive two different responses as the values for emailAddressProvided and emailAddressChecked. The value for emailAddressChecked will always be the shortened version of the address without the dot notation. This also ensures we don’t check multiple email addresses that are, in fact, the same account.


Optionally, you can also use the ‘correct’ parameter to remove certain invalid characters such as spaces, slashes, square brackets etc. Example using the ‘correct’ parameter. The user enters an email address john99]@gmail.com. Here is the API call that would be made: The API will automatically remove the invalid character ‘]’ and send the corrected version through for validation. Example results based on the above API call:


Authentication without the license key – ACL Many situations require that the API license key is not displayed, e.g. where the API is used within a client-side application such as jQuery in a website form. Access the API at: For ACL based authentication (without using the key), it is not necessary to include the license key in the request. Other parameters (e.g. ‘correct’) are supported as in the key based example. In this case, the authentication will be done using the domain name hosting the files where the API is embedded. Please send us a list of your domain names that will be hosting your API integration so that we can add them to the permitted list for your account.


Querying API usage via the API We have implemented a feature allowing for an API query. The result now also includes the number of credits remaining. If you call the API with usage = 1 then you get today’s usage and this month’s usage e.g. But with a date from a previous month added to the query then the month stats are for that month. This allows for programmatically checking usage before making a call that will eat into account usage. Example result:


To use the integration code examples with the API V3, ensure the value of $url = https://api.emailverifyapi.com/v3/lookups/json in the following respective examples below. PHP Code Example C# Code Example VB.net Code Example Java Code Example Python Code Example Perl Code Example jQuery ACL (Keyless) Code Example jQuery With License Key Code Example AngularJS With License Key Code Example