Email Validation v1.1

Performs a full mailbox validation on the supplied email address.

Version 1.1

Takes one or more email addresses as an input and performs validation, returning a list of the results. The maximum number of input email addresses is 100 per call.

Resource URL

    POST    https://hosted.mastersoftgroup.com/harmony/rest/{locale}/validate/email

Request

The request body is an EmailRestRequest object:

    {
        "payload": [ 
            { "address": "[e-mail]" }, 
            { "address": "[e-mail]" } 
        ],
        "sourceOfTruth": "VE_ALL",
        "featureOptions: { "timeout": "1500" }
    }
    

Response

The response body is an EmailRestResponse object. Sample responses below:

{
    "status": "SUCCESS",
    "messages": [],
    "payload": [
        {
            "address": "[e-mail]",
            "attributes": {
                "domain_exists": "VALID",
                "mailserver_exists": "VALID",
                "email_valid": "VALID",
                "message": "Email address does not exist on mail server.",
                "email_exists": "INVALID",
                "do_not_mail": "FALSE", 
                "disposable": "FALSE", 
                "rolebased": "FALSE", 
                "catchall": "FALSE", 
                "spamtrap": "FALSE", 
                "abuse": "FALSE", 
                "free_email": "TRUE", 
                "accountname": "jim", 
                "domain": "hotmail.com", 
                "domain_age_days": "1052", 
                "suggested_email": "", 
                "deliverable": "VALID", 
                "hashsha256": "4c93fb55adc0297ee4086a8d047ff7ca694784c690703eab0f215685db180f37",
                "hashmd5": "3e9385d795906ee1a3e04aa93bfa3a41",
                "hashsha1": "7a90bf8dcac4717728d4f36e291ff17255dadeb2"
            },
            "domainValidated": true,
            "mailServerValidated": true,
            "mailBoxValidated": false,
            "blackListValidated": true,
            "formatValidated": true
        },
        {
            "address": "[e-mail]",
            "attributes": {
                "hashsha1": "b89406e03dd7cf89e55c1353f9fd3f5e940abbf4",
                "hashmd5": "04097aeaaafe1b91144a006ea0dc2921",
                "hashsha256": "ffc36bbab1970bfa0aeef8fdb989f396dea4d0ad2f7df3d6dd2349430c71a944",
                "domain_exists": "UNKNOWN",
                "mailserver_exists": "UNKNOWN",
                "email_valid": "UNKNOWN",
                "message": "Timeout Exceeded",
                "email_exists": "UNKNOWN"
            },
            "formatValidated": true,
            "blackListValidated": true,
            "domainValidated": false,
            "mailServerValidated": false,
            "mailBoxValidated": false
        }
    ]
}

Response Elements

The response attributes are listed below. These are listed in the order expected when validating email addresses.

Element Name	Description	Example
address	the email address that is being validated.	[e-mail]
mailBoxValidated	if the mailbox is valid and deliverable if true	true/false
mailServerValidated	Determines if the mailserver is valid or not.	true/false
domainValidated	Determines if the domain is valid or not.	true/false
blackListValidated	Determines if the user has blocked this email address. You can block email addresses via Harmony Console	true/false
formatValidated	Determines if the syntax of the email address is valid	true/false
email_valid	Attribute of the email format validation. Determines if the email format is valid or not. Valid - format is valid. (blank) - format is invalid and API timeout	VALID, (blank)
domain_exists	Attribute of the domain validation. Determines if the domain exists and can receive email. Valid - domain exists. Invalid - domain does not exist or can't receive email. Unknown - unable to determine if valid or not; check email.	VALID, INVALID, UNKNOWN
mailserver_exists	Attribute of the mailserver validation. Determines if the mailserver is valid or not. Valid - mailserver exists. Invalid - there is no mail server present at this domain. Unknown - unable to determine if valid or not; check email.	VALID, INVALID, UNKNOWN
email_exists	Attribute of the mailbox validation. Valid - email is verified. Invalid - email address does not exist on mail server. Unknown - unable to verify email address.	VALID, INVALID, UNKNOWN
message	additional information	Email verified. Domain does not exist or cannot receive email. Email address does not exist on mail server. Email server will not verify this specific email address. Please check email, unable to determine if valid or invalid. There is no mail server present at this domain. Possible Email greylisting - please retry after a minute. This mail server accepts all requests. Unable to verify email address.
do_not_mail	Recommended you check before sending. Often these are blocked or cause you reputation damage on email sending platforms.	true/false
disposable	Known Temporary email address that is used to hide the real email address of the user. These usual last 15 min to 6 months.	true/false
rolebased	Role based email (eg sales@, marketing@) and not a individuals email address	true/false
catchall	Catch all based email (eg donotreply@ client@) and not a individuals email address	true/false
spamtrap	Known spamtrap address	true/false
abuse	These emails are of people who are known to click the abuse links in emails	true/false
free_email	If the email comes from a free provider	true/false
accountname	The portion of the email address before the "@" symbol.	jim
domain	The portion of the email address after the "@" symbol.	hotmail.com
domain_age_days	Age of the email domain in days or [null]	10054
suggested_email	Suggestive Fix for an email typo	[e-mail]
deliverable	status type field	valid, invalid, catch-all, spamtrap, abuse,do_not_mail, unknown
hashsha256	Hashed using sha256	4c93fb55adc02....

Response timings

We make live calls to domains located all around the world that have variable protocols and capacities. The vast majority of calls, in particular to major ISP's operate within the desire response times. A small amount a domains will result in network, server latency and security protocols variables like mail transfer agents that can impact the overall latency of the service.

This is an industry wide issue when sending requests to domains around the world. Our expected ranges of performance results are:

• 96%-98% of all domains sit between 1 to 5 seconds.

• All the major ISP's are 1 to 3 secs.

• 2%-4% will take longer than 5 seconds.

This can causing impacts in your customer experience. If this is an issue for your implementation we recommend implementing a timeout function when calling our Email Validation API and handling as an 'unknown' response to the end user.