Github Code Examples
For the latest updates regarding our API code examples please view our Gist at GitHub.
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.
Access where your domain has been whitelisted
https://api.emailverifyapi.
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 |
| 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
