Response email object

Checks are done on the email address itself (including its associated domain name and DNS records).

There is also a list of breaches (i.e. leaked lists of user details) that the email address has appeared in. This is useful to see if the email address has history on the internet, to confirm the email address is not throwaway.

The email object is always available in the result where an email field is provided as an input.

If the lookup is unsuccessful, success will be false. If the email address is not in the correct format (see email validity below), or can't receive email, valid will be false. The success and valid properties are always present, but other properties only exist where success and valid are true.

Examples

Unsuccessful:

{
    ...
    "email": {
        "success": false,
        "valid": null
    },
    ...
}

Successful but not valid:

{
    ...
    "email": {
        "success": true,
        "valid": false
    },
    ...
}

Valid:

{
    ...
    "email": {
        "success": true,
        "valid": true,
        "email": "[email protected]",
        "local_part": "dan",
        "normalized_email": "[email protected]",
        "normalized_local_part": "dan",
        "domain": "example.com",
        "domain_tld": "com",
        "domain_tld_high_risk": false,
        "digits_count": 0,
        "name_match": true,
        "free": true,
        "disposable": false,
        "business": false,
        "breaches_count": 8,
        "breaches_list": [
            "CafePress",
            "PDL",
            "Lastfm",
            ...
        ],
        "seen_hour": 1,
        "seen_day": 1,
        "seen_month": 1,
        "seen_quarter": 1,
        "unique_devices": 1
    },
    ...
}

Email normalization:

{
    ...
    "email": {
        "success": true,
        "valid": true,
        "email": "[email protected]",
        "local_part": "DaNgErOuS+dan",
        "normalized_email": "[email protected]",
        "normalized_local_part": "dangerous",
        "domain": "gmail.com",
        "domain_tld": "com",
        "domain_tld_high_risk": false,
        "digits_count": 0,
        "name_match": true,
        "free": true,
        "disposable": false,
        "business": false,
        "breaches_count": 8,
        "breaches_list": [
            "CafePress",
            "PDL",
            "Lastfm",
            ...
        ],
        "seen_hour": 1,
        "seen_day": 1,
        "seen_month": 1,
        "seen_quarter": 1,
        "unique_devices": 1
    },
    ...
}

tip

Although it may seem a good idea to save the normalized form of the email (normalized_email) in your database, it's best to use the email field as this how the user intends to be identified.

You should generally use the normalized_email field only for deciding if an email address is already registered. Better still, use the seen_x properties to make decisions on uniqueness.

Properties

Property	Description	Type
success	Set to true only if the lookup is successful.	boolean
valid	Set to true where the email is in the correct format and the domain has DNS records that confirm it can accept email (i.e. email is deliverable). See the section below on email validity. null if the lookup failed.	boolean or null
email	The full email address, with unsupported unicode characters removed, the domain name in lowercase, and other basic formatting applied.	string
local_part	The part of the email address before the @ character, with unsupported unicode characters removed, and other basic formatting applied.	string
normalized_email	The full email address with further normalization applied. The local_part is lowercased, and email provider specific features (such as + addressing in Gmail) is accounted for. It is recommended to use this form where you need to check for email duplicates.	string
normalized_local_part	The part of the email address before the @ character with further normalization applied. It is lowercased, and email provider specific features (such as + addressing in Gmail) is accounted for.	string
domain	The domain name.	string
domain_tld	The top-level domain (i.e. .com, .co.uk).	string or null
domain_tld_high_risk	Whether the TLD for the domain is known to be particuarly high risk. Some domains are popular with disposable email services.	boolean or null
digits_count	The number of digits in the local_part of the domain name. A high number of digits may indicate a throwaway address.	integer
name_match	Whether the name provided alongside the email address is a fuzzy/loose match for the local_part of the address. Always false where no name is provided.	boolean
free	Set to true where the address is likely to be from a free email provider such as Hotmail or Gmail.	boolean
disposable	Set to true where the address is likely to be from a disposable or temporary email provider such as Mailinator.	boolean
business	For convenience, set to true where free and disposable are both false. Indicates a likely private email address such as a business/work address.	boolean
seen_hour	Number of times events have been seen with this normalized email address since the start of the previous hour.	integer
seen_day	Number of times events have been seen with this normalized email address since yesterday.	integer
seen_month	Number of times events have been seen with this normalized email address since the start of last month.	integer
seen_quarter	Number of times events have been seen with this normalized email address since the start of the last calendar quarter.	integer
unique_devices	Number of unique devices associated with this normalized email address.	integer
breaches_count	The number of breaches that the email address was found in.	integer
breaches_list	An array of strings representing the names of breaches that the email address was found to be a part of, an empty array if not part of any breach or if the lookup fails.	array of strings

Email validity

As well as checking the format of the email address, and deliverability (using DNS MX records), valid will be false for addresses with unsafe Unicode characters, obsolete (very rarely used) email address syntax, special use domain names like @localhost, and domains without a dot. These technically may be valid but are likely not wanted or expected.