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

https://api.emailverifyapi.com/v3/lookups/[FORMAT]?email=[EMAIL]&key=[YOUR_API_KEY]

The value for FORMAT can be specified as either JSON, JSONP or XML. It is case-insensitive.

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]

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

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

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

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