QUICK START GUIDE [V3 API]

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]

API DOCUMENTATION V3

The URL to pass to the API is: https://api.emailverifyapi.com/v3/lookups/[FORMAT]?email=[EMAIL]&key=[YOUR_API_KEY]

Parameter	Value	Mandatory or Optional
format	json, jsonp or xml	Mandatory
email	the email address to be validated	Mandatory
key	your unique API key	Mandatory unless your domain has been whitelisted
correct	0 or 1	Optional - 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.com” Validation 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.

API RESPONSES

The table below details the main API responses from the Email Checker V3 API.

Response	Return Code(s) or Value(s)	Explanation
address	Email address	Validates the email address that has been verified
username	username	The username part of the email address before the @
domain	domain name	The domain name part of the email address after the @
md5Hash	md5 hash value	A unique MD5 hash value computed from the email address
suggestion	Email address	A suggestion for emails with suspected typos
validFormat	true or false	Whether the email address was in a valid RFC format
deliverable	true or false	If we are able to deliver to the email address
fullInbox	true or false	Whether the destination Inbox was full and therefore rejecting messages
hostExists	true or false	If the destination mail server exists
catchAll	true or false	The domain for the email address will accept any username part before the @, therefore it cannot be validated
gravatar	false — Always return false at the moment	If there is a gravatar.com avatar configured for the email address
role	Email address	The email address is a default "role" - see next table below
disposable	true or false	Email is a known disposable, typically quick-turnaround addresses that are disposed of quickly
free	true or false	Email 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.

THE TYPO CORRECTION FEATURE

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:

ACCESS CONTROL LIST – ACL

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.

API USAGE QUERY

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:

INTEGRATION CODE EXAMPLES

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