System Status: Operational

Zero Spam API
Documentation

Integrate the world’s most accurate threat intelligence into your stack. Identify malicious IPs and disposable emails in real-time.

Get License Key

View Endpoints

# Single IP Lookup

curl "https://www.zerospam.org/wp-json/v3/query?license_key=YOUR_LICENSE_KEY&ip=8.8.8.8"

# IP & Email Lookup

curl "https://www.zerospam.org/wp-json/v3/query?license_key=YOUR_LICENSE_KEY&ip=8.8.8.8|1.2.3.4&email=spam@example.com|test@malicious.net"

# Response Structure

{ "status": 200, "body_response": { "queries_limit": 10000, "queries_made": 1, "queries_remaining": 9999, "ip_addresses": { "8.8.8.8": { "ip_address": "8.8.8.8", "permalink": "https://www.zerospam.org/lookup/8.8.8.8/", "confidence": 0.45, "date_added": "2024-01-15 10:30:00", "last_updated": "2024-06-22 14:15:00", "country_code": "US", "country_name": "United States", "num_reports": 12 } } }, "response": [] }

Query API

Look up IP addresses and email addresses to check if they have been reported as spam or malicious. This is the primary endpoint for threat checking.

GET

https://www.zerospam.org/wp-json/v2/query

Query IP addresses and/or email addresses for spam reports and threat data.

Parameters

Parameter	Type	Description
ip	String	The IP address you want to check. You can check multiple IPs at once by separating them with a pipe character (\|). The number of IPs you can check at once depends on your license tier. Example: “1.2.3.4\|5.6.7.8”
email	String	The email address you want to check. You can check multiple emails at once by separating them with a pipe character (\|). Example: “bot@spam.com\|fake@test.com”
license_key	String	Your Zero Spam license key. This authenticates your request and determines what data you can access. Example: “XXXX-XXXX-XXXX-XXXX”

Important

You must provide at least one of `ip` or `email`. You can provide both to check IPs and emails in a single request.

Limits & Quotas

Explorer	10/day
Essentials	10,000/day
Business	50,000/day
Platform	Unlimited

Unlock Real-Time Threat Intelligence

Query real-time threat data from thousands of websites to block the same attackers hitting everyone else.

Threat Confidence Scoring — Not all spam is equal. Our scoring algorithm weighs report volume, recency, complaint diversity, and reporting sources to calculate precise threat levels for every IP and email
Source Intelligence — Go beyond block/allow decisions. See exactly where attacks originate with country, city, ISP, connection type, and reverse DNS data
Activity History — Bad actors don’t stop. Track when each threat was first seen, last seen, and how many sites have reported them to catch persistent offenders

Get a License Today

Response Data

Every API response includes these standard fields that tell you about the request status and your usage:

Parameter	Type	Description
status	integer	The HTTP status code. A value of 200 means your request was successful. Other codes indicate errors (see Error Responses below).
response	array	This is empty when everything works correctly. When there’s an error, it contains a code explaining what went wrong.
body_response	object	This is where all the actual data lives – your lookup results and usage statistics.

body_response Data

These fields appear inside `body_response` and tell you about your API usage:

Parameter	Type	Description
queries_limit	integer	The maximum number of API calls you’re allowed to make during your current billing period.
queries_made	integer	How many API calls you’ve made so far this billing period, including the current request. Use this to track your usage.
queries_remaining	integer	How many API calls you have left before hitting your limit. When this reaches zero, your requests will be rejected until your billing period resets.
ip_addresses	object	Contains the results for any IP addresses you looked up. Each IP you queried becomes a key, with its threat data as the value. Only appears if you included the `ip` parameter. See IP Address Data.
email_addresses	object	Contains the results for any email addresses you looked up. Each email you queried becomes a key, with its threat data as the value. Only appears if you included the `email` parameter. See Email Address Data.

Error Responses

When something goes wrong, you’ll receive one of these error responses:

Status	Response Code	What It Means
401	no_license_key	You didn’t include a license_key in your request. Every request must include your license key.
401	invalid_license_key	The license key you provided doesn’t exist or has been deactivated. Double-check your key.
403	exceeded_requests	You’ve used all your API calls for this billing period. Wait for your period to reset or upgrade your plan.
400	license_error	There’s a problem with your license product configuration. Contact support.
400	invalid_request	You didn’t provide any valid IP addresses or email addresses to check.

IP Address Data

When you look up an IP address, you receive the following information. The amount of data depends on your license tier. Fields you don’t have access to will show upgrade_for_access instead of the actual value.

Parameter	Type	Access	Description
ip_address	string	All Licenses	The IP address that was checked. This confirms which IP this data is about when you’re checking multiple IPs at once.
permalink	string	All Licenses	A direct link to the Zero Spam website page for this IP. You can visit this page to see more details and the public history of this IP address.
confidence	float	All Licenses	Our calculated threat score from 0.00 (safe) to 1.00 (definitely malicious). A score above 0.5 suggests you should block this IP.
date_added	string	Premium	When Zero Spam first received a spam report about this IP address. The format is a MySQL datetime like `2024-01-15 10:30:00`. Older records with continued activity suggest persistent bad actors.
last_updated	string	Premium	When we last received new information about this IP. Recent updates mean the IP is still actively causing problems. Format is MySQL datetime.
hostname	string	Premium	Detailed raw report data logs.
ip_type	string	Premium	The type of IP address – residential (home internet), datacenter (servers), mobile, or VPN/proxy. Datacenter and VPN IPs are more commonly used by spammers.
continent_code	string	Premium	Two-letter code for the continent where this IP is located (NA=North America, EU=Europe, AS=Asia, etc.).
continent_name	string	Premium	The full name of the continent (North America, Europe, Asia, etc.).
country_code	string	Premium	Two-letter ISO country code like US (United States), GB (United Kingdom), or CN (China). Useful for geo-blocking high-risk countries.
country_name	string	Premium	The full country name like United States, United Kingdom, or China.
region_code	string	Premium	State or province code. For US addresses, this is the two-letter state code like CA (California) or NY (New York).
region_name	string	Premium	Full name of the state, province, or region.
city	string	Premium	The city where this IP is located. Note that IP geolocation is approximate and may not be 100% accurate.
zip	string	Premium	Postal or ZIP code for the IP location. May be approximate.
latitude	float	Premium	Geographic latitude coordinate (north/south position on the globe). Use with longitude to plot on a map.
longitude	float	Premium	Geographic longitude coordinate (east/west position on the globe). Use with latitude to plot on a map.
dmz	string	Premium	The latitude and longitude formatted in degrees-minutes-seconds format (DMZ), which is the traditional way to express coordinates.
num_reports	integer	Premium	The total number of times this IP has been reported to Zero Spam as spam or malicious. Higher numbers indicate more problematic IPs. An IP with 100+ reports is almost certainly malicious.
compliants_reported	array	Premium	A list of the types of spam complaints filed against this IP. Examples include “comment_spam”, “registration_spam”, “contact_form_spam”. Shows you what kind of malicious activity this IP is known for.
emails_reported	array	Premium	Email addresses that have been reported in connection with this IP address. Useful for identifying coordinated spam campaigns where the same person uses multiple emails.
reports_list	array	Premium	The complete list of individual spam reports for this IP. Each report includes details like the reporting website, date, type of spam, and detection method. Use this for forensic analysis.
num_domains_submitted_reports	integer	Premium	How many different websites have reported this IP. An IP reported by 50 different websites is more dangerous than one reported 50 times by the same website.
num_compliants_reported	integer	Premium	The number of different complaint categories this IP has been reported for. IPs that do many types of spam (comments, registrations, forms) are typically automated bots.

Email Address Data

When you look up an email address, you receive the following information. The amount of data depends on your license tier.

Parameter	Type	Access	Description
email_address	string	All Licenses	The email address that was checked. Confirms which email this data is about when checking multiple emails at once.
permalink	string	All Licenses	A direct link to the Zero Spam website page for this email. Visit to see the public history and reports for this email address.
confidence	float	All Licenses	Our calculated threat score from 0.00 (safe) to 1.00 (definitely spam). Considers report count, recency, and complaint types. Emails above 0.5 should likely be blocked.
date_added	string	Premium	When Zero Spam first received a report about this email address. Format is MySQL datetime like `2024-01-15 10:30:00`.
last_updated	string	Premium	When we last received new information about this email. Recent updates indicate the email is still actively being used for spam.
num_reports	integer	Premium	Total number of spam reports filed against this email address. Higher numbers indicate more problematic addresses.
email_names	array	Premium	Names that have been associated with this email address across spam reports. Spammers often use fake names, so seeing many different names is suspicious.
email_job_titles	array	Premium	Job titles that have been used in spam submissions from this email. Often fake or inflated titles used to seem legitimate.
email_companies	array	Premium	Company names associated with this email across reports. Can help identify patterns in business email compromise or impersonation.
email_locations	array	Premium	Geographic locations that have been associated with this email. Multiple far-apart locations for one email is suspicious.
email_phone_numbers	array	Premium	Phone numbers submitted alongside this email in spam reports. Useful for identifying coordinated spam operations.
compliants_reported	array	Premium	Types of spam complaints filed against this email (comment_spam, registration_spam, etc.). Shows what malicious activities this email is known for.
reports_list	array	Premium	Complete list of individual reports for this email with full details. Use for investigating the history of a suspicious email.
num_domains_submitted_reports	integer	Premium	Number of different websites that have reported this email. An email reported by many sites is definitely problematic.
num_compliants_reported	integer	Premium	Number of different complaint categories. Emails used for multiple types of spam are typically automated.

Zero Spam APIDocumentation