Email Validation

Performs a full mailbox validation on the supplied email address.

Version 1.2

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.

7th September 2023, implementing a change to:

Add new attributes do_not_send, risk, reason and subdomain.

Depreciate attributes do_not_mail (replaced with do_not_send), spamtrap, abuse, domain_age_days. See here for more information.

Previous documentation for Email validation v1.1 is available here

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]" }, 
            { "address": "[e-mail]" } 
        ],
        "sourceOfTruth": "VE_ALL",
        "featureOptions: { "timeout": "1500" }
    }
    

Response

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

{
            "address": "[e-mail]",
            "attributes": {
                "catchAll": "false",
                "hashmd5": "3e9385d795906ee1a3e04aa93bfa3a41",
                "hashsha256": "4c93fb55adc0297ee4086a8d047ff7ca694784c690703eab0f215685db180f37",
                "domain_exists": "VALID",
                "mailserver_exists": "VALID",
                "deliverable": "DELIVERABLE",
                "email_valid": "true",
                "message": "Email verified.",
                "disposable": "false",
                "email_exists": "VALID",
                "do_not_mail": "false",
                "hashsha1": "7a90bf8dcac4717728d4f36e291ff17255dadeb2",
                "do_not_send": "false",
                "rolebased": "false",
                "domain": "hotmail.com",
                "subdomain": "false",
                "risk": "LOW",
                "account": "jim"
            },
            "reason": [],
            "formatValidated": true,
            "blackListValidated": true,
            "domainValidated": true,
            "mailServerValidated": true,
            "mailBoxValidated": true
        },
        // Example: Email address does not exist on mail server
        {
            "address": "[e-mail]",
            "attributes": {
                "catchAll": "false",
                "hashmd5": "efa811854abb0ad7de2579a349c2d470",
                "hashsha256": "1bc88ec6d822c4bd4c88b399ee7874effea66c26e5a1ac895dbd263792d26ca4",
                "domain_exists": "VALID",
                "mailserver_exists": "VALID",
                "deliverable": "UNDELIVERABLE",
                "email_valid": "true",
                "message": "Email address does not exist on mail server.",
                "disposable": "false",
                "email_exists": "INVALID",
                "do_not_mail": "false",
                "hashsha1": "225da63df3d2b1fb9fd6b49e7f8068da88c23733",
                "do_not_send": "false",
                "rolebased": "false",
                "domain": "yahoo.com",
                "subdomain": "false",
                "risk": "HIGH",
                "account": "jimmy"
            },
            "reason": [
                "mailbox_does_not_exist"
            ],
            "formatValidated": true,
            "blackListValidated": true,
            "domainValidated": true,
            "mailServerValidated": true,
            "mailBoxValidated": false
        },
```
        //request timeout example
        {
            "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,
            "reason": ["req_timeout"]
        }
    ]
}

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. It will validate do_not_send. If onboarding (particularly B2B) use this. If marketing, use deliverable.	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. Please check email, unable to determine if valid or invalid. This mail server accepts all requests. Unable to verify email address.
do_not_send	Often these emails 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 (e.g., sales@, marketing@) and not an individual's email address.	true/false
catchAll	Catch all based email (e.g., donotreply@ client@) and not an individual's email address.	true/false
subdomain	email is subdomain email.	true/false
account	The portion of the email address before the "@" symbol.	jim
domain	The portion of the email address after the "@" symbol.	hotmail.com
risk	Potential impact on sender reputation score depending on all aspects.	LOW, MEDIUM, HIGH, UNKNOWN
suggested_email	Suggestive Fix for an email typo	[e-mail]
deliverable	status type field	deliverable, undeliverable, do_not_send, catch_all or unknown
reason	List of reasons validation was unsuccessful	see reason list
hashsha256	Hashed using sha256	4c93fb55adc02....

Reason List

Reason	Description
catch_all	The validity of the recipient address cannot be determined as the provider accepts any and all email regardless of whether or not the recipient’s mailbox exists.
disallow_list	Email is on your disallow list.
failed custom grammar check	The mailbox failed our local-part grammar check.
format_failed	Failed format syntax check.
high_risk_domain	Information obtained about the domain indicates it is high risk to send email to.
immature_domain	The domain is newly created based on the WHOIS information.
long_term_disposable	The mailbox has been identified as a long term disposable address. Long term disposable addresses can be quickly and easily deactivated by users, but they will not expire without user intervention.
mailbox_does_not_exist	The mailbox is undeliverable or does not exist.
mailbox_is_disposable_address	The mailbox has been identified to be a disposable address. Disposable address are temporary, generally one time use, addresses.
mailbox_is_role_address	The mailbox is a role based address (ex. support@…, marketing@…).
no_mx / No MX host found	The recipient domain does not have a valid MX host.
req_timeout	Timed out by request timeout setting e.g. your timeout setting. You may need to increase your timeout setting.
smtp_timeout	Timed out by smtp provider.
subdomain_mailer	The recipient domain is identified to be a subdomain and is not on our exception list. Subdomains are considered to be high risk as many spammers and malicious actors utilize them.
tld_risk	The domain has a top-level-domain (TLD) that has been identified as high risk.
unknown_provider	The MX provider is an unknown provider.

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

Depreciated Attributes

In August 2023, the following attributes have been depreciated.

do_not_mail: depreciated and replaced with do_not_send because of naming confusion with anti-spam compliance. do_not_mail and do_not_send is a recommendation to protect your sender reputation score.

spamtrap: Depreciated due to privacy compliance.

abuse: Depreciated due to privacy compliance.

domain_age_days: Depreciated and superseded with new attributes contained within reason being high_risk_domain, immature_domain, tld_risk.