Custom Integrations - Making Email Validity Checks Documentation

This API endpoint allows you to perform Email Validation and email reputation checks on behalf of your users in an almost identical fashion to our standard user API structure.

Calling Email Validation & Email Reputation

https://www.ipqualityscore.com/webhooks/ExampleIntegration/json/email_check

Request Parameters

Parameter	Description	Example Value / Format
key	Your site's domain or the domain that requested this integration. REQUIRED	google.com
secret	Your user's current secret created during the authentication process. REQUIRED	char(128)
email	The email you wish to validate for your user. REQUIRED	email address, must contain @
fast	When this parameter is enabled our API will not perform an SMTP check with the mail service provider, which greatly increases the API speed. Syntax and DNS checks are still performed on the email address as well as our disposable email detection service. This option is intended for services that require decision making in a time sensitive manner.	boolean
timeout	Maximum number of seconds to wait for a reply from a mail service provider. If your implementation requirements do not need an immediate response, we recommend bumping this value to 20. Any results which experience a connection timeout will return the "timed_out" variable as true. Default value is 7 seconds.	integer (1-60)
suggest_domain	Force analyze if the email address's domain has a typo and should be corrected to a popular mail service. By default, this test is currently only performed when the email is invalid or if the "recent abuse" status is true.	boolean

Result

Note: Only JSON responses are available from this API and this API should ONLY be called server side for security reasons.

Parameter	Description	Example Value / Format
valid	Does this email address appear valid?	boolean
disposable	Is this email suspected of belonging to a temporary or disposable mail service? Usually associated with fraudsters and scammers.	boolean
timed_out	Did the connection to the mail service provider timeout during the verification? If so, we recommend increasing the "timeout" variable above the default 7 second value. Lookups that timeout with a "valid" result as false are most likely false-positives and should be not be trusted.	boolean
deliverability	How likely is this email to be delivered to the user and land in their mailbox. Values can be "high", "medium", or "low".	string
suspect	Is this email likely to be a "catch all" where the mail server verifies all emails tested against it as valid? If this value is true, then we suspect the "valid" result may be tainted and there is not a guarantee that the email address is truly valid. This value can also be true when the mail server is returning a temporary error.	string
smtp_score	Validity score of email server's SMTP setup. Range: "-1" - "3". Scores above "-1" can be associated with a valid email. -1 = invalid email address 0 = mail server exists, but is rejecting all mail 1 = mail server exists, but is showing a temporary error 2 = mail server exists, but accepts all email 3 = mail server exists and has verified the email address	integer
overall_score	Overall email validity score. Range: "0" - "4". Scores above "1" can be associated with a valid email. 0 = invalid email address 1 = dns valid, unreachable mail server 2 = dns valid, temporary mail rejection error 3 = dns valid, accepts all mail 4 = dns valid, verified email exists	integer
first_name	Suspected first name based on email. Returns "CORPORATE" if the email is suspected of being a generic company email. Returns "UNKNOWN" if the first name was not determinable.	string
common	Is this email from a common email provider? ("gmail.com", "yahoo.com", "hotmail.com", etc.)	boolean
generic	Is this email suspected as being a catch all or shared email for a domain? ("admin@", "webmaster@", "newsletter@", "sales@", "contact@", etc.)	boolean
dns_valid	Does the email's hostname have valid DNS entries? Partial indication of a valid email.	boolean
honeypot	Is this email believed to be a "honeypot" or "SPAM trap"? Bulk mail sent to these emails increases your risk of being blacklisted by large ISPs & ending up in the spam folder.	boolean
recent_abuse	This value will indicate if there has been any recently verified abuse across our network for this email address. Abuse could be a confirmed chargeback, fake signup, compromised device, fake app install, or similar malicious behavior within the past few days.	boolean
frequent_complainer	Indicates if this email frequently unsubscribes from marketing lists or reports email as SPAM.	boolean
suggested_domain	Default value is "N/A". Indicates if this email's domain should in fact be corrected to a popular mail service. This field is useful for catching user typos. For example, an email address with "gmai.com", would display a suggested domain of "gmail.com". This feature supports all major mail service providers.	string
request_id	A unique identifier for this request that can be used to lookup the request details or send a postback conversion notice.	string
success	Was the request successful?	boolean
message	A generic status message, either success or some form of an error notice.	string
errors	Array of errors which occurred while attempting to process this request.	array of strings

Example Code


// URL for this request.
$URL = 'https://www.ipqualityscore.com/webhooks/ExampleIntegration/json/email_check';

// Configuration items for this request. NOTE: $secret will be user specific not application specific.
$key = 'example.com';
$secret = 'WkYwHzjeWMqGBuJKBA98Ko63arm3Cd6n3gwfucxaldFPyflJQ4X4oYmaHZmEudy7RGzF3v7I8GCVvaPpCBbsJD17XdGWYSunc8dmpvbxkH6QlcT5SxuH2pmt2Dhu4cDM';

// The email you wish to validate.
$email = 'admin@ipqualityscore.com';

// Prepare POST fields.
$fields = array(
	'secret' => $secret,
	'key' => $key,
	'email' => $email
);
	
// Create CURL.
$curl = curl_init();
	
// Configure CURL
curl_setopt($curl, CURLOPT_URL, $URL);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, true);
curl_setopt($curl, CURLOPT_POST, 1);

// Set POST Parameters
curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($fields));

// Fetch URL
$result = curl_exec($curl);

// GET response code.
$response_code = curl_getinfo($curl, CURLINFO_HTTP_CODE);

// Close CURL
curl_close($curl);
	
// Handle result.
if((int) $response_code === 200){
	// JSON Decode
	$output = json_decode($result, true);
	
	// If our request was successful.
	if($output['success'] === true){
	
		// Was the email valid?
		if($output['valid'] === true){
			echo "The email ".$email." is valid";
		} else {
			echo "The email ".$email." is invalid.";
		}
	} else {
		echo $output['message'];
	}
} else {
	echo "There appears to be an unforeseen error. Please contact support if this persists.";
}