Quick Start Guide

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: https://api.emailverifyapi.com/api/a/v1?key=YOUR_API_KEY&email=test@tester.com

API Documentation

The URL to pass to the API is:

https://api.emailverifyapi.com/api/a/v1?key=YOUR_API_KEY&email=test@tester.com

ParameterValueMandatory or Optional
keyyour unique API keyMandatory
emailthe email address to be validatedMandatory
correct1 (this will remove certain invalid characters)
0 (this will leave the email untouched)
Optional

Important Notes Regarding Integration
1. The response is a JSON data string and a JSON function must be used to decode it. Please do not rely on parsing a text string as this may cause issues.
2. We recommend that any “Unknown” results are treated as “OK” (valid). This will prevent potentially valid emails from being rejected.

The Response would be:

ResponseDescriptionExample values
statusThe validation result‘Ok’, ‘Bad’, ‘Unknown’
additionalStatusAdditional information for BAD and UNKNOWN resultsNoMxServersFound
emailAddressProvided The exact email address passed to the API including obvious typos and errorstest@tester.com
emailAddressCheckedThe actual email address validatedtest@tester.com
emailAddressSuggestionA suggested alternative if a common typo was noticed e.g. if ‘fred@hotmail.cm’ was providedfred@hotmail.com

Main Status Response Codes

The table below details the Main Status Response Codes from the Email Checker API.

ResponseExplanation
OKVerification passes all checks including Syntax, DNS, MX, Mailbox, Deep Server Configuration, Grey Listing
BadVerification fails checks for definitive reasons (e.g. mailbox does not exist)
UnknownConclusive verification result cannot be achieved due to mail server configuration or anti-spam measures. See table “Additional Status Codes”.

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:

When an email address is returned with a status of Bad or Unknown we return the detailed reason as part of the response in the additionalStatus value. For a full list of additional status values, please refer to the list below.

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 e.g.

This allows for programmatically checking usage before making a call that will eat into account usage.

Additional Status Codes

The table below details the Additional Status Codes from the Email Checker API.

Status CodeMeaning
NoneNo additional information is available. This status differs from a TransientNetworkFault as it should not be retried (the result will not change). There are a few known reasons for this status code for example the target mx record uses Office 365 or a mail provider implementing custom mailbox shutdowns.
AtSignNotFoundThe required ‘@’ sign is not found in email address.
DomainIsInexistentThe domain (i.e. the bit after the ‘@’ character) defined in the email address does not exist, according to DNS records. A domain that does not exist cannot have email boxes. A domain that does not exist cannot have email boxes.
DomainIsWellKnownDeaThe domain is a well known Disposable Email Address DEA.

There are many services available that permit users to use a one-time only email address. Typically, these email addresses are used by individuals wishing to gain access to content or services requiring registration of email addresses but same individuals not wishing to divulge their true identities (e.g. permanent email addresses). DEA addresses should not be regarded as valid for email send purposes as it is unlikely that messages sent to DEA addresses will ever be read.
MailboxFullThe mailbox is full. Mailboxes that are full are unable to receive any further email messages until such time as the user empties the mail box or the system administrator grants extra storage quota. Most full mailboxes usually indicate accounts that have been abandoned by users and will therefore never be looked at again. We do not recommend sending emails to email addresses identified as full.
MailboxDoesNotExistThe mailbox does not exist. 100% confidence that the mail box does not exist.
NoMxServersFoundThere are no mail servers defined for this domain, according to DNS. Email addresses cannot be valid if there are no email servers defined in DNS for the domain.
ServerDoesNotSupportInternationalMailboxesThe server does not support international mailboxes. International email boxes are those that use international character sets such as Chinese / Kanji etc. International email boxes require systems in place for Punycode translation. Where these systems are not in place, email verification or delivery is not possible.
ServerIsCatchAllThe server is configured for catch all and responds to all email verifications with a status of OK. Mail servers can be configured with a policy known as Catch All. Catch all redirects any email address sent to a particular domain to a central email box for manual inspection. Catch all configured servers cannot respond to requests for email address verification.
SuccessSuccessful verification.100% confidence that the mail box exists.
TooManyAtSignsFoundToo many ‘@’ signs found in email address. Only one ‘@’ character is allowed in email addresses.
UnknownThe reason for the verification result is unknown.
TransientNetworkFaultA temporary network fault occurred during verification. Please try again later. Verification operations on remote mail servers can sometimes fail for a number of reasons such as loss of network connection, remote servers timing out etc. One other possible cause of a temporary fault is Grey Listing (i.e. the target mail server blocks the first connection attempt and requests a delayed re-try). These conditions are usually temporary. Retrying verification at a later time will usually result in a positive response from mail servers. Please note that setting an infinite retry policy around this status code is inadvisable as there is no way of knowing when the issue will be resolved within the target domain or the grey listing resolved, and this may affect your daily quota.
PossibleSpamTrapDetectedA possible spam trap email address or domain has been detected. Spam traps are email addresses or domains deliberately placed on-line in order to capture and flag potential spam based operations. Our advanced detection heuristics are capable of detecting likely spam trap addresses or domains known to be associated with spam trap techniques. We do not recommend sending emails to addresses identified as associated with known spam trap behaviour. Sending emails to known spam traps or domains will result in your ESP being subjected to email blocks from a DNS Block List. An ESP cannot tolerate entries in a Block List (as it adversely affects email deliver-ability for all customers) and will actively refuse to send emails on behalf of customers with a history of generating entries in a Block List.

Integration Code Examples

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