Email Validation API – Documentation

Introduction

The URL to pass to the API is:

https://api.emailcleansing.com/api/a/v1?key=yourapikey&email=test@tester.com
Parameter Value Mandatory or Optional
key your unique API key Mandatory
email the email address to be validated Mandatory
correct 1 (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:

{
"status":"Bad",
"additionalStatus":"MailboxDoesNotExist",
"emailAddressProvided":"test@tester.com",
"emailAddressChecked":"test@tester.com",
"emailAddressSuggestion":""
}

Main Status Response Codes

Response Description Example values
status The validation result ‘Ok’, ‘Bad’, ‘Unknown’
additionalStatus Additional information for BAD and UNKNOWN results NoMxServersFound
emailAddressProvided The exact email address passed to the API including obvious typos and errors test@tester.com
emailAddressChecked The actual email address validated test@tester.com
emailAddressSuggestion A suggested alternative if a common typo was noticed e.g. if ‘fred@hotmail.cm’ was provided fred@hotmail.com
Response Explanation
Ok Verification passes all checks including Syntax, DNS, MX, Mailbox, Deep Server Configuration, Grey Listing
Bad Verification fails checks for definitive reasons (e.g. mailbox does not exist)
Unknown Conclusive verification result cannot be achieved due to mail server configuration or anti-spam measures. See table “Additional Status Codes”

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

https://api.emailcleansing.com/api/a/v1?key=yourapikey&email=john99]@gmail.com&correct=1

The API will automatically remove the invalid character ‘]’ and send the corrected version through for validation. Example results based on the above API call:

{
"status":"Ok",
"additionalStatus":"None",
"emailAddressProvided":"john99]@gmail.com",
"emailAddressChecked":"john99@gmail.com",
"emailAddressSuggestion":""
}

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 additional Status value. For a full list of additional status values, please refer to the list below.

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:

https://api.emailcleansing.com/api/a/v1?email=test@tester.com

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.

Additional Status Codes

Status Code: None

No 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.

Status Code: AtSignNotFound

The required ‘@’ sign is not found in email address.

Status Code: DomainIsInexistent

The 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.

Status Code: DomainIsWellKnownDea

The 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.

Status Code: MailboxDoesNotExist

The mailbox does not exist.

100% confidence that the mail box does not exist.

Status Code: NoMxServersFound

There 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.

Status Code: ServerDoesNotSupportInternationalMailboxes

The 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.

Status Code: ServerIsCatchAll

The 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.

Status Code: Success

Successful verification. 100% confidence that the mail box exists.

Status Code: TooManyAtSignsFound

Too many ‘@’ signs found in email address.

Only one ‘@’ character is allowed in email addresses.

Status Code: Unknown

The reason for the verification result is unknown.

Status Code: TransientNetworkFault

A 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.

Status Code: PossibleSpamTrapDetected

A 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 Blcok 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.