<< Back to Categories

Getting Started

About the Email Verification API

The IPQS Email Verification API estimates deliverability rates by detecting invalid mailboxes as well as disposable and fraudulent email addresses, spam traps, bounced delivery, and honeypots via our simple-to-use Email Reputation API. Verify email addresses and identify abusive emails & invalid addresses in real-time with a reliable, low-latency API request.

Adding the Email Verification API to your registration and checkout pages allows you to validate email addresses in real-time as users interact with your site or app. This proactive approach helps prevent the creation of fake accounts, typos, bounces, invalid user data, and other forms of abuse. You can also process batch files by uploading a CSV file through the user platform.

API Request URLs

You can use the following URLs to submit email addresses to the Email Verification API. Replace USER_EMAIL_HERE with the email address to analyze.

JSON

XML

Example Request

Lookup with timeout set to 60

Provides better accuracy if response time is not an issue. Timeout can be a value between 1 and 60. The default timeout is 7 seconds.

Example Responses

Success Responses

This is an example success response in JSON format. Details about each of these variables can be found in Response Parameters.

{
	"valid": true,
	"timed_out": false,
	"disposable": false,
	"first_name": "Unknown",
	"deliverability": "high",
	"smtp_score": 3,
	"overall_score": 4,
	"catch_all": false,
	"generic": false,
	"common": true,
	"dns_valid": true,
	"honeypot": false,
	"frequent_complainer": false,
	"suspect": false,
	"recent_abuse": false,
	"fraud_score":25,
	"leaked": false,
	"suggested_domain": "N\/A",
	"domain_velocity": "high",
	"domain_trust": "trusted",
	"user_activity": "medium",
	"associated_names":{ "status":"Enterprise Plus or higher required.","names":[] },
	"associated_phone_numbers":{ "status":"Enterprise Plus or higher required.","phone_numbers":[] },
	"first_seen": {
		"human": "3 months ago",
		"timestamp": 1568061634,
		"iso": "2019-09-09T16:40:34-04:00"
	},
	"domain_age": {
		"human": "3 months ago",
		"timestamp": 1568061634,
		"iso": "2019-09-09T16:40:34-04:00"
	},
	"success": true,
	"spam_trap_score": "none",
	"risky_tld": false,
	"spf_record": true,
	"dmarc_record": true,
	"sanitized_email": "validated@example.com",
	"mx_records":["us-smtp-inbound-1.mimecast.com", "aspmx.l.google.com"],
	"request_id": "4JAer3sX6rF3PO",
	"a_records": ["192.0.2.110"]
}

This is an example success response in XML format. Details about each of these variables can be found in Response Parameters.

<result>
	<timed_out>false</timed_out>
	<valid>true</valid>
	<disposable>false</disposable>
	<first_name>Unknown</first_name>
	<deliverability>high</deliverability>
	<smtp_score>3</smtp_score>
	<overall_score>4</overall_score>
	<catch_all>false</catch_all>
	<generic>false</generic>
	<common>true</common>
	<dns_valid>true</dns_valid>
	<honeypot>false</honeypot>
	<frequent_complainer>false</frequent_complainer>
	<suspect>false</suspect>
	<recent_abuse>false</recent_abuse>
	<fraud_score>25</fraud_score>
	<leaked>false</leaked>
	<suggested_domain>N/A</suggested_domain>
	<domain_velocity>high</domain_velocity>
	<domain_trust>trusted</domain_trust>
	<user_activity>medium</user_activity>
	<risky_tld>false</risky_tld>
	<spf_record>true</spf_record>
	<dmarc_record>true</dmarc_record>
	<spam_trap_score>none</spam_trap_score>
	<first_seen>
		<human>3 months ago</human>
		<timestamp>1568061634</timestamp>
		<iso>2019-09-09T16:40:34-04:00</iso>
	</first_seen>	
	<domain_age>
		<human>3 months ago</human>
		<timestamp>1568061634</timestamp>
		<iso>2019-09-09T16:40:34-04:00</iso>
	</domain_age>
	<sanitized_email>validated@example.com</sanitized_email>
	<success>true</success>
	<request_id>4JAer3sX6rF3PT</request_id>
</result>
	<mx_records>
		<mx_records>us-smtp-inbound-1.mimecast.com</mx_records>
	</mx_records>
	<a_records>
		<a_records>192.0.2.110</a_records>
	</a_records>

Error Responses

Example errors that you may encounter when accessing our API due to an exhausted credit balance or an invalid email address.

{
	"success":false,
	"message":"You have insufficient credits to make this query. Please contact IPQualityScore support if this error persists.",
	"request_id":"4OTORR352FU0p"
}

{
	"success":false,
	"message":"Invalid email address. Please check the email and try again.",
	"request_id":"4OTORR4EWpl0m"
}

Next Steps

Tailor your API requests to match your specific needs with additional request parameters and other advanced options. Or learn more about each of the variables included in the responses you receive.

EXAMPLE CODE

PHP
PYTHON

// Your API Key.
$key = 'YOUR_API_KEY_HERE';
	
// The email you wish to validate.
$email = 'noreply@ipqualityscore.com';

/*
* Set the maximum number of seconds to wait for a reply
* from an email service provider. If speed is not a concern 
* or you want higher accuracy we recommend setting this in 
* the 20 - 40 second range in some cases. Any results which 
* experience a connection timeout will return the "timed_out" 
* variable as true. Default value is 7 seconds.
*/
$timeout = 1;
	
/*
* If speed is your major concern set this to true, 
* but results will be less accurate.
*/
$fast = 'false';

/*
* Adjusts abusive email patterns and detection rates
* higher levels may cause false-positives (0-2)
*/
$abuse_strictness = 0;
	
// Create parameters array.
$parameters = array(
	'timeout' => $timeout,
	'fast' => $fast,
	'abuse_strictness' => $abuse_strictness
);
	
// Format our parameters.
$formatted_parameters = http_build_query($parameters);
	
// Create the API URL.
// URL Encode the Email Address.
$url = sprintf(
	'https://www.ipqualityscore.com/api/json/email/%s/%s?%s', 
	$key,
	urlencode($email),
	$formatted_parameters
);

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt($curl, CURLOPT_CONNECTTIMEOUT, $timeout);

$json = curl_exec($curl);
curl_close($curl);

// Decode the result into an array.
$result = json_decode($json, true);

// Check to see if our query was successful.
if(isset($result['success']) && $result['success'] === true){
	// NOTICE: If you want to use one of the examples below remove
	// any lines containing /*, */ and *-, then remove * from any of the
	// the remaining lines.
	
	/*
	*- Example 1: We'd like to allow all valid email addresses.
	* 
	* if($result['valid'] === true){
	*		echo "Email is valid.";
	* } else {
	* 	echo "Email is NOT valid.";
	* }
	*/
	
	/*
	*- Example 2: We'd like to allow valid emails that haven't 
	*- been reported as abusive.
	* 
	* if($result['valid'] === true && $result['recent_abuse'] === false){
	*		echo "Email is valid.";
	* } else {
	* 	echo "Email is NOT valid.";
	* }
	*/
	
	/*
	*- Example 3: We'd like to allow valid emails or allow
	*- emails that timed out, but passed other quality checks
	*- and not allow emails reported as abusive
	*- Note: Timeouts occur when the mail provider does not respond fast enough to verify the email inbox.
	* 
	* if(
	*		$result['recent_abuse'] === false &&
	*		($result['valid'] === true || $result['timed_out'] === true && $result['disposable'] === false && $result['dns_valid'] === true)
	*	){
	*		echo "Email is valid.";
	* } else {
	* 	echo "Email is NOT valid.";
	* }
	*/
}

import json
import requests
from typing import Union


# Should be treated like an environment variable and secret.
API_KEY = "YOUR_API_KEY_HERE"


class Validate(object):
    """
    Class for interacting with the IPQualityScore API.

    Attributes:
        key (str): Your IPQS API key.
        format (str): The format of the response. Default is 'json', but you can also use 'xml'.
        base_url (str): The base URL for the IPQS API.

    Methods:
        email_validation_api(email: str, timeout: int = 1, fast: str = 'false', abuse_strictness: int = 0) -> str:
            Returns the response from the IPQS Email Validation API.
    """

    key = None
    format = None
    base_url = None

    def __init__(self, key, format="json") -> None:
        self.key = key
        self.format = format
        self.base_url = f"https://www.ipqualityscore.com/api/{self.format}/"

    def email_validation_api(self, email: str, timeout: int = 7, fast: str = 'false', abuse_strictness: int = 0) -> str:
        """
        Returns the response from the IPQS Email Validation API.

        Args:
            email (str):
                The email you wish to validate.
            timeout (int):
                Set the maximum number of seconds to wait for a reply from an email service provider.
                If speed is not a concern or you want higher accuracy we recommend setting this in the 20 - 40 second range in some cases.
                Any results which experience a connection timeout will return the "timed_out" variable as true. Default value is 7 seconds.
            fast (str):
                If speed is your major concern set this to true, but results will be less accurate.
            abuse_strictness (int):
                Adjusts abusive email patterns and detection rates higher levels may cause false-positives (0 - 2).

        Returns:
            str: The response from the IPQS Email Validation API.
        """

        url = f"{self.base_url}email/{self.key}/{email}"

        params = {
            "timeout": timeout,
            "fast": fast,
            "abuse_strictness": abuse_strictness
        }

        response = requests.get(url, params=params)
        return response.text

    def phone_number_validation_api(self, phone_number: str, country: Union[str, list], strictness: int = 0) -> str:
        """
        Returns the response from the IPQS Phone Number Validation API.

        Args:
            phone_number (str):
                The phone number you wish to validate.
            country (str or list):
                You can optionally provide us with the default country or countries this phone number is suspected to be associated with.
                Our system will prefer to use a country on this list for verification or will require a country to be specified in the event the phone number is less than 10 digits.
            strictness (int):
                Adjusts the strictness of the phone number validation. Higher levels may cause false-positives (0 - 2)

        Returns:
            str: The response from the IPQS Phone Number Validation API.
        """

        url = f"{self.base_url}phone/{self.key}/{phone_number}"

        params = {
            "country": country,
            "strictness": strictness
        }

        response = requests.get(url, params=params)
        return response.text


if __name__ == "__main__":

    email = 'support@ipqualityscore.com'
    phone_number = '18007132618'

    v = Validate(API_KEY)
    print(v.base_url)

    print(v.email_validation_api(email))
    print(v.phone_number_validation_api(phone_number, 'US'))

Ready to eliminate fraud?

Start fighting fraud now with 5,000 Free Lookups!

We're happy to answer any questions or concerns.

Chat with our fraud detection experts any day of the week.

Call us at: (800) 713-2618

Schedule a Demo Sign Up