API


The Spam.org API allows you to access all of the tools and datasets offered on Spam.org using an automated process from within your server or script. The API is available to all registered users and registration is always free.

The purpose of the Spam.org API is to streamline the process of reporting, resolving and downloading spam and network abuse complaints.

Here are a few practical uses of our API:

  • Automated List Downloads - Download our block lists and complaints lists on-demand and import them into your firewall or security workflow.
  • Automated Abuse Reporting - Submit abuse complaints directly from your servers to ours.
  • Automated Abuse Search - Perform automatd queries to determine if an IP or domain is on our block list.

Response Format

The API returns all data in JSON format. A typical JSON response is provided below.

{"success":true,"message":"","redirect_url":"","results":{"total":0,"count":0,"start":0,"end":0,"data":[]}}

A breakdown of the returned datapoints is provided below:

  • success - Boolean variable (true/false only) indicating whether or not the API query was successful
  • message - An error message, if the API command failed, otherwise this field is blank
  • redirect_url - A URL containing the final output of the results, in case the results were too big to provide in a JSON response. This is typically used when a resultset requested contains a file.
  • results - An object array containing the results and additional metadata.
  • total - Total number of items matching the query (total results count).
  • count - Actual number of results as part of this response. Large responses must be queried in batches.
  • start - The index of the first item in the result set. This is returned for all resultsets but generally only used on resultsets that have to be queried in batches.
  • end - The index of the last item in the result set. This is returned for all resultsets but generally only used on resultsets that have to be queried in batches. This index is used as a starting position for the next query.
  • data - An object array containing the actual data.

If your API responses do not contain the expected JSON object provided above it is..

Request Format

The request format is provided below. If you are logged in (recommended) your API key will automatically be replaced in the example queries.

A breakdown of the URL components is provided below:

  • URL - The URL to the Spam.org API, this is generally http://api.spam.org/
  • a - The action command [required]. All available actions are provided in the next section. This command must be specified with all queries.
  • k - Your API key [required]. If you are logged in all of the example queries will automatically replace the demo API key with your API key.
  • start - Starting position for batched results [optional]. In situations where the results are too large to be returned in a single query (default is 10,000 results per response), this is the starting position (expressed as an integer) of the next batch of results.

API Commands

This section lists all available API commands and provides examples queries.

get_sobl_ip

This command retrieves a list of all IP addresses on the SOBL (Spam.org Block List).

get_sobl_domain

This command retrieves a list of all domains addresses on the SOBL (Spam.org Block List).

get_complaints_summary

This command retrieves a summary of complaints filed against an internet resource. The following internet resources are supported by this call: IP, domain, registrar, registry, domain extension (TLD). You must specify a complaint type using the &type=X flag from one of the following options: 'ip','isp','registrar','registry','tld'.

The output of this command is condensed to reduce bandwidth usage and deliver fast responses. Unlke results of other API calls, results of this call are comma delimited and stripped of property names. The first row in the result includes the column headers. The result format is similar to a CSV file. Field values (actual data such as registrar names, registry names, ISP names, etc) are guaranteed not to contain commas in the field values.

A sample query that will show IP complaints is provided below.

get_subcomplaints

This command retrieves a list of subcomplaints filed against an internet resource. The following internet resources are supported by this call: IP, domain. You must specify a complaint type using the &type=X flag from one of the following options: 'ip','domain'.

The output of this command is includes a UID field (as well as many other fields) which may be used to further retrieve detailed information about a specific subcomplaint.

A sample query that will show IP subcomplaints is provided below.

get_subcomplaint

This command retrieves detailed information about a subcomplaint. The level of information provided depends on whether you are the authority for which this complaint was generaed. In other words, if the complaint was sent to you (ex: abuse@yourorganization and that email is associated with your Spam.org account) then you will have access to all pertinent data points necessary to resolve this complaint, including the raw email content.

This command requires that you specify the UID of the subcomplaint you are inquiring about. The UID can be obtained from the get_subcomplaints API call.

A sample query that will show detailed subcomplaint information for a specific subcomplaint is provided below.

resolve_subcomplaint

This command resolves a subcomplaint. Only subcomplaints associated with your account can be resolved. This command only works on Organization level accounts.

This command requires that you specify the UID of the subcomplaint you are trying to resolve as well as a valid resolution response. A valid resolution response describes what you did to resolve the complaint and must match one of the following options: Warned User, Disconnected User, Disconnected Hosting Account, Blocked Mail Port, Other

A sample query which resolves a subcomplaint with the resolution 'Blocked Mail Port' is provided below.

search_sobl_ip

This command searches the SOBL and subcomplaint list to determine if the specified IP or block is listed. You can search multiple IPs/blocks at the same time (for example, you can search all of your owned/managed IP ranges at once).

This command requires that you specify one or more IP addresses or ranges (ex: 5.5.5.0//24) in CIDR notation. The smallest supported range for this search is /8. Only IPs which exist on the SOBL will be returned.

A sample query which searches 5.5.5.0/24 and 6.6.6.0/8 is provided below.

search_sobl_domain

This command searches the SOBL and subcomplaint list to determine if the specified domain is listed. You can search multiple domains at the same time by separating them with a comma. All domains are automatically converted to root domains (ex: subdomain.yourdomain.com => yourdomain.com).

This command requires that you specify one or more domains you wish to check using the &d=DOMAIN flag.

A sample query which searches test.com and great.com is provided below.

report_spam

This command files a spam or network abuse complaint.

This command requires that you specify the complaint reason as well as submit the original email (in the case of a spam complaint). The email must be submitted as a base 64 encoded string. It is necessary to use a POST method to execute this API call.

The following flags are required:

  • type - The following types are supported: "spam" (for spam complaints) and "network abuse" for all other complaints
  • spam_reason - The following reasons are supported: "Not Subscribed","Unsubscribed","Virus/Malware Email","Phishing Email"
  • data - A base64 ecnoded complete email message or network abuse log.