Email Risk and Domain Verification API

The following document highlights the details of the Email Risk and Domain Verification API.

API Description

Objective

The Email Risk and Domain Verification API validates and retrieves information about an email address. It reveals if the input email has been involved in any data breaches that might have exposed sensitive information such as names, passwords, or other personal details linked to the email.

Input	Output
The email address to be verified	The verification status of the email address, details about the domain, the associated company's name, whether the domain is compliant with security protocols, the history of any data breaches involving the email, and an estimate of how long the email address has been in use.

API URL

https://ind-engine.thomas.hyperverge.co/v1/emailBasic

API Endpoint

emailBasic

Overview

The Email Risk and Domain Verification API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format, and you should send the request body as JSON through a POST request.

Method - POST

Authentication

You need a unique pair of application ID ( appId ) and application key ( appKey ) from HyperVerge to verify your identity for accessing the Email Risk and Domain Verification API.

Headers

Header	Mandatory / Optional	Description	Input Format
content-type	Mandatory	This parameter defines the media type for the request payload	application/json
appId	Mandatory	The application identifier shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
appKey	Mandatory	The application key shared by HyperVerge. You can find the details in the dashboard's credentials tab	This should be a unique value
transactionId	Mandatory	Unique ID for the customer journey	Any defined unique value mapped to a transaction in your business ecosystem

Inputs

The following table provides the details of the parameters required for the Email Risk and Domain Verification API's request body:

Parameter	Mandatory / Optional	Type	Description	Input Format	Default Value
email	Mandatory	string	The email address to be verified	Valid email address string	Not Applicable

Request

The following code snippet demonstrates a standard curl request for the Email Risk and Domain Verification API:

curl --location --request POST 'https://ind-engine.thomas.hyperverge.co/v1/emailBasic' \
--header 'Content-Type: application/json' \
--header 'appId: <Enter_the_HyperVerge_appId>' \
--header 'appKey: <Enter_the_HyperVerge_appKey>' \
--header 'transactionId: <Enter_the_HyperVerge_transactionID>' \
--data '{
    "email": "<Enter_the_email_address>"
}'

Success Response

The following code snippet demonstrates a success response from the Email Risk and Domain Verification API:

Email Address Not Compromised

{
  "status": "success",
  "statusCode": "200",
  "result": {
    "deliverable": true,
    "domainName": "<Domain_Name>",
    "tld": "<Top_Level_Domain>",
    "creationTime": "<Domain_Creation_Time>",
    "updateTime": "<Domain_Update_Time>",
    "expiryTime": "<Domain_Expiry_Time>",
    "registered": "<Domain_Registration_Status>",
    "companyName": "<Company_Name_Associated_With_Domain>",
    "disposable": "<Is_Email_Disposable>",
    "freeProvider": "<Is_Email_From_Free_Provider>",
    "dmarcCompliance": "<DMARC_Compliance>",
    "spfStrict": "<SPF_Strictness_Status>",
    "suspiciousTld": "<Suspicious_TLD_Status>",
    "websiteExists": "<Does_Website_Exist>",
    "acceptAll": "<Does_Domain_Accept_All_Emails>",
    "custom": "<Custom_Field>",
     "breach": {
            "isBreached": false,
            "noOfBreaches": 0,
            "firstBreach": null,
            "lastBreach": null,
            "breaches": []
        },
    "emailTenure": "<Email_Tenure_in_Years>"
  }
}

Email Address Compromised

{
    "status": "success",
    "statusCode": "200",
    "result": {
        "deliverable": true,
        "domainName": "<Domain_Name>",
        "tld": "<Top_Level_Domain>",
        "creationTime": "<Creation_Time>",
        "updateTime": "<Update_Time>",
        "expiryTime": "<Expiry_Time>",
        "registered": true,
        "companyName": "<Company_Name>",
        "disposable": false,
        "freeProvider": true,
        "dmarcCompliance": null,
        "spfStrict": null,
        "suspiciousTld": null,
        "websiteExists": true,
        "acceptAll": false,
        "custom": null,
        "breach": {
            "isBreached": true,
            "noOfBreaches": "<Number_Of_Breaches>",
            "firstBreach": "<First_Breach_Date>",
            "lastBreach": "<Last_Breach_Date>",
            "breaches": [
                {
                    "platformName": "<Platform_Name>",
                    "domainName": "<Domain_Name>",
                    "breachDate": "<Breach_Date>"
                },
                {
                    "platformName": "<Platform_Name>",
                    "domainName": "<Domain_Name>",
                    "breachDate": "<Breach_Date>"
                },
                {
                    "platformName": "<Platform_Name>",
                    "domainName": "<Domain_Name>",
                    "breachDate": "<Breach_Date>"
                },
                {
                    "platformName": "<Platform_Name>",
                    "domainName": "<Domain_Name>",
                    "breachDate": "<Breach_Date>"
                },
                {
                    "platformName": "<Platform_Name>",
                    "domainName": "<Domain_Name>",
                    "breachDate": "<Breach_Date>"
                },
                {
                    "platformName": "<Platform_Name>",
                    "domainName": "<Domain_Name>",
                    "breachDate": "<Breach_Date>"
                },
                {
                    "platformName": "<Platform_Name>",
                    "domainName": "<Domain_Name>",
                    "breachDate": "<Breach_Date>"
                },
                {
                    "platformName": "<Platform_Name>",
                    "domainName": "<Domain_Name>",
                    "breachDate": "<Breach_Date>"
                }
            ]
        },
        "emailTenure": "<Email_Tenure>"
    }
}

Success Response Details

The following table outlines the details of the success response from the Email Risk and Domain Verification API:

Parameter	Type	Description
status	string	The status of the request
statusCode	string	The HTTP status code for the response
result	object	The JSON object containing the email verification details
deliverable	boolean	Indicates whether the email address actually exists or not, using a fast SMTP-MX check
domainName	string	The domain of the email address of the user
tld	string	The top-level domain of the email address
creationTime	string	The date and time when the domain was created (UTC time zone)
updateTime	string	The date and time when the domain was last updated (UTC time zone)
expiryTime	string	The date and time when the domain is set to expire (UTC time zone)
registered	boolean	Indicates whether the email's domain is registered
companyName	string	The name of the company that manages the reservation of the domain name
disposable	boolean	Indicates if the email's domain is fraudulent such as disposable email, previous fraudulent domains
freeProvider	boolean	Indicates whether the email address is from a free email provider such as gmail, hotmail
dmarcCompliance	object	Indicates if the email's domain is DMARC (Domain-based Message Authentication Reporting and Conformance) enforced
spfStrict	object	Indicates if the SPF is sufficiently strict enough to prevent spoofing
suspiciousTld	object	Indicates if the email's top-level-domain is likely to be fraudulent or risky
websiteExists	boolean	Indicates if the email's domain has a website or not
acceptAll	boolean	Indicates if the server is set to receive all emails at this domain
custom	object	Indicates if customer domain configuration is present
breach	object	Information about any data breaches related to the email address
breach.isBreached	boolean	Indicates whether the email address has been involved in any data breaches
breach.noOfBreaches	integer	The number of data breaches involving the email address
breach.firstBreach	string	The date when the email was first compromised, null if not applicable
breach.lastBreach	string	The date when the email was last compromised, null if not applicable
breach.breaches	array	Array of objects containing breach details
breach.breaches[].platformName	string	The name of the platform where the email address was compromised
breach.breaches[].domainName	string	The domain of the platform where the email address was compromised
breach.breaches[].breachDate	string	The date when the email address was compromised for the particular platform
emailTenure	number	The estimated tenure of the email address in years

Failure Response

The following code snippet demonstrates a failure response from the Email Risk and Domain Verification API when the provided email address is invalid:

{
    "status": "success",
    "statusCode": "200",
    "result": {
        "deliverable": false,
        "domainName": "<Domain_Name>",
        "tld": "<Top_Level_Domain>",
        "creationTime": "<Creation_Time>",
        "updateTime": null,
        "expiryTime": null,
        "registered": true,
        "companyName": "<Company_Name>",
        "disposable": false,
        "freeProvider": false,
        "dmarcCompliance": null,
        "spfStrict": null,
        "suspiciousTld": null,
        "websiteExists": true,
        "acceptAll": false,
        "custom": null,
        "breach": {
            "isBreached": false,
            "noOfBreaches": 0,
            "firstBreach": null,
            "lastBreach": null,
            "breaches": []
        },
        "emailTenure": null
    }
}

Error Responses

The following are some error responses from the Email Risk and Domain Verification API:

Input Validation Error

{
    "status": "failure",
    "statusCode": 400,
    "message": "Email cannot be empty"
}

Invalid Event Type

{
    "status": "failure",
    "statusCode": 400,
    "message": "Invalid event type"
}

Missing/Invalid credentials

{
    "message": "Missing/Invalid credentials",
    "statusCode": 401,
    "status": "failure"
}

Internal Server Error

{
    "message": "Internal Server Error",
    "statusCode": 500,
    "status": "failure" 
}

Error Response Details

A failure or error response contains a failure status with a relevant status code and error message.
The following table lists all error responses:

Status Code	Error Message	Error Description	Error Resolution
400	Email cannot be empty	The request is missing the email parameter in the request body	Ensure the request includes the email parameter with a valid email address
400	Invalid Input	The provided email does not match the standard email template	Provide a valid email address that follows the standard email format
400	Invalid event type	The event type provided in the request is invalid	Verify and provide a valid event type in the request
401	Missing/Invalid credentials	The request is either missing the mandatory appId and appKey combination or has invalid values	Verify and provide valid appId and appKey credentials
403	Access Denied	Access to the Email Risk and Domain Verification API has been denied	Contact the HyperVerge team for resolution
500	Internal Server Error	Kindly check the request headers or contact the HyperVerge team for resolution.	Check the request headers or contact the HyperVerge team for resolution