Spam Trap Email Detection API

Remove Spam Trap Emails with Detection by API Lookup

Improve email deliverability and inbox rates with the IPQS spam trap detection API. This email validation service is built to cleanse email marketing lists from harmful honeypots which can hurt sender scores and IP address or domain reputation. Detecting spam traps can greatly improve deliverability rates and significantly reduce the chance of being blacklisted by RBLs, ESPs, and mail providers.

This email hygiene service works best when combined with the email verification API to validate emails with bounce testing. Preventing spam traps and invalid accounts from entering your email marketing lists is the ultimate goal, as this ensures you can successfully inbox on popular services like gmail.com, yahoo.com, aol.com, hotmail.com, etc.

Spam Trap & Complainer API for Email Marketing

In addition to identifying honeypots, the spam trap detection API can also identify frequent complainers which are sensitive to marketing messages. These accounts may be overly aggressive with reporting email as spam. This service is an extension of the IPQS Email Validation API. Our spam trap database and complainer lists are updated daily with millions of new low reputation email addresses.

Get an accurate understanding of your current email deliverability with our email spam check tool that can analyze all aspects of your email. This quick test will verify your email content and headers have a valid SPF, DKIM, and PTR records for your email domain. The content is also analyzed for any possible issues that could cause blacklisting or bounced messages.

Private API Key

Please login or create a free account to access your API Key.

NOTE: Keep your spam trap lookup API key hidden as it can be used to view data on your account.

Request URLs

The XML and JSON URLs below can be used to fetch the result using cURL or a similar method. The example below displays our end points for the spam trap email address detection API. Please replace "USER_EMAIL_HERE" with the request email.

JSON:

XML:

JSON Example Requests

API Lookup with Your Email Address

JSON Success Response Example

{
	"valid": true,
	"deliverability": "high",
	"catch_all": false,
	"honeypot": false,
    "spam_trap_score": "none",
	"frequent_complainer": false,
	"suggested_domain": "N\/A",
	"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,
	"sanitized_email": "validated@example.com",
	"request_id": "4JAer3sX6rF3PO"
}

NOTE: For a description of each field listed above please consult the response documentation below.

XML Success Response Example

<result>
	<valid>true</valid>
	<deliverability>high</deliverability>
	<catch_all>false</catch_all>
	<honeypot>false</honeypot>
	<frequent_complainer>false</frequent_complainer>
	<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>

NOTE: For a description of each field listed above please consult the response documentation below.

JSON Error Response Examples

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

{
	"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"
}

Spam Trap API Response Field Definitions

Analyzing Spam Trap & Complainer Email Results
Anytime the spam trap email address API service returns "spam_trap_score" as high, it is likely that the email address is an active spam trap. Sending marketing messages to this user would be strongly discouraged. Confidence scores as medium can also be removed at your own preference. The API results can also indicate "frequent_complainer" as true, which would indicate the email address has recently been involved in many reports against marketing messages.

Field

Description

Possible Values

valid

Does this email address appear valid?

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

catch_all

Is this email likely to be a "catch all" where the mail server verifies all emails tested against it as valid? It is difficult to determine if the address is truly valid in these scenarios, since the email's server will not confirm the account's status.

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

spam_trap_score

Confidence level of the email address being an active SPAM trap. Values can be "high", "medium", "low", or "none". We recommend scrubbing emails with "high" or "medium" statuses. Avoid "low" emails whenever possible for any promotional mailings.

string

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

first_seen

Field	Description	Possible Values
human	A human description of how long it's been since IPQS first analyzed this email address. (Ex: 3 months ago)	string or null
timestamp	The unix time since epoch when this email was first analyzed by IPQS. (Ex: 1568061634)	integer
iso	The time this email was first analyzed by IPQS in ISO8601 format (Ex: 2019-09-09T16:40:34-04:00)	string

object

domain_age

Field	Description	Possible Values
human	A human description of when this domain was registered. (Ex: 3 months ago)	string or null
timestamp	The unix time since epoch when this domain was first registered. (Ex: 1568061634)	integer
iso	The time this domain was registered in ISO8601 format (Ex: 2019-09-09T16:40:34-04:00)	string

object

sanitized_email

Sanitized email address with all aliases and masking removed, such as multiple periods for Gmail.com.

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

// 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';
	
// Create parameters array.
$parameters = array(
	'timeout' => $timeout,
	'fast' => $fast
);
	
// Format our parameters.
$formatted_parameters = http_build_query($parameters);
	
// Create our API URL.
$url = sprintf(
	'https://www.ipqualityscore.com/api/json/email/%s/%s?%s', 
	$key,
	$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){
	*- Example 1: Flag high confidence spam traps and frequent complainer addresses
	* 
	* if(
	*		($result['spam_trap_score'] === "high" || $result['frequent_complainer'] === true)
	*	){
	*		echo "Email is likely to cause deliverability issues for your sending domain and IP address.";
	* } else {
	* 	echo "Email is clean.";
	* }
	*/
}

import json
import requests

# You may need to install Requests pip
# python -m pip install requests

class IPQS:
    key = "YOUR_API_KEY_HERE"

    def email_validation_api(self, email: str, vars: dict={}) -> dict:
        url = "https://www.ipqualityscore.com/api/json/email/%s/%s" % (self.key, email)
        x = requests.get(url, params = vars)
        return (json.loads(x.text))

if __name__ == "__main__":

    #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'


    #custom feilds
    additional_params = {
        'timeout' : timeout,
	    'fast' : fast
    }


    ipqs = IPQS()
    result = ipqs.email_validation_api(email, additional_params)

    # Check to see if our query was successful.
    if 'success' in result and result['success']:

        #Example 1: Flag disposable and abusive emails
        if result['spam_trap_score'] == "high" or result['frequent_complainer'] == True:
            print('Email is likely to cause deliverability issues for your sending domain and IP address.')
        else:
            print('Email is clean.')