APIs

You are welcome to experiment with and incorporate this API in your application.

For premade scripts that probably integrate into your forum software, visit the members contributions page.

Code examples

You can find examples of code, to access the API, on the API code examples page. Currently, there is PHP but we hope that more people will provide code in as many languages as possible

Notice

This API is NOT to be used as a general software firewall. Checking every incoming connection against the API will be treated as a denial of service attack against us and will result in the immediate blocking of any offending IP numbers

How to Use

It's just an HTTP GET, and the page will return some simple XML indicating the type of search performed, whether it appears or not in our database, and the number of times it appears (frequency).

API queries against our server are currently limited to 20,000 per day. If you require more, consider using the DNSBL below or by asking us very nicely.

A typical successful response would look like this:

<response success="true">
    <type>ip</type>
    <appears>yes</appears>
    <lastseen>2007-09-18 05:48:53</lastseen>
    <frequency>2</frequency>
</response>

Examples


Multiple queries

Queries for some or all fields can be made in a single query, as here

Multi field queries will return data in the following default XML format

<response success="true">
    <type>ip</type>
    <appears>yes</appears>
    <lastseen>2009-10-26 11:55:07</lastseen>
    <frequency>78</frequency>
    <type>email</type>
    <appears>yes</appears>
    <lastseen>2009-06-25 00:24:29</lastseen>
    <frequency>2</frequency>
</response>

Bulk queries

Up to 15 queries of any field combination can be made by constructing the fields as an array, as below

This query format is not compatible with the default XML format and because of this, the standard format this that query will return results as will XMLDOM

The default result will be formatted as below. Notice that the queried field is returned with the results so that matches can be made on the client. This is to remove any possible issues with results being reported out of order as submitted. If an email address has been altered for testing, such as when normalisation is required, then the normalized email is also returned in the results.

This format supports all XML and serialized response. Any fields over the 15 limit are disgarded. If the square brackets are excluded from any field, then that query will be ignored

Each bulk query of 5 field tests consumes one query and 0.2 for each field over 5

<?xml version="1.0" encoding="UTF-8"?>
<root>
  <success>1</success>
  <username>
    <value>spammer</value>
    <lastseen>2011-01-10 00:31:06</lastseen>
    <frequency>6</frequency>
    <appears>1</appears>
  </username>
  <username>
    <value>anotherspammer</value>
    <frequency>0</frequency>
    <appears>0</appears>
  </username>
  <email>
    <value>w.a.spigi%2B25%40gmail.com</value>
    <normalized>waspigi@gmail.com</normalized>
    <lastseen>2011-02-07 22:27:08</lastseen>
    <frequency>50</frequency>
    <appears>1</appears>
  </email>
  <email>
    <value>spam%40spam.com</value>
    <lastseen>2010-08-08 16:59:06</lastseen>
    <frequency>1</frequency>
    <appears>1</appears>
  </email>
  <email>
    <value>test%40test.com</value>
    <lastseen>2011-02-10 23:51:37</lastseen>
    <frequency>94</frequency>
    <appears>1</appears>
  </email>
  <ip>
    <value>1.2.3.4</value>
    <lastseen>2011-02-17 13:02:31</lastseen>
    <frequency>214</frequency>
    <appears>1</appears>
  </ip>
</root>

Strict XML results

The default XML result is not XML compliant when returning multiple fields. This cannot be corrected for legacy reasons but strict results can be returned by using f=xmldom or f=xmlcdata. These parameters will return data as below by passing the f parameter to the API, eg

http://www.stopforumspam.com/api?email=g2fsehis5e@mail.ru&username=MariFoogwoogy&f=xmlcdata

f=xmldom

<?xml version="1.0" encoding="UTF-8"?>
<root>
<success>1</success>
<username>
<frequency>0</frequency>
<appears>0</appears>
</username>
<ip>
<lastseen>2010-07-17 19:32:57</lastseen>
<frequency>184</frequency>
<appears>1</appears>
</ip>
</root>

f=xmlcdata

<?xml version="1.0" encoding="UTF-8"?>
<array>
  <success><![CDATA[1]]></success>
  <username>
    <frequency><![CDATA[0]]></frequency>
    <appears><![CDATA[0]]></appears>
  </username>
  <ip>
    <lastseen><![CDATA[2010-07-17 19:32:57]]></lastseen>
    <frequency><![CDATA[184]]></frequency>
    <appears><![CDATA[1]]></appears>
  </ip>
</array>

Using these two XML formats will also set the correct HTTP headers to XML


Serialized results

We currently support two serialization formats, which can be used by passing f=format to the query

The two formats supported are json using f=json and php serialize() using f=serial

Examples for php serialize results as

This would return the following result

a:3:{s:7:"success";b:1;s:5:"email";a:3:{s:8:"lastseen";s:19:
"2009-06-25 00:24:29";s:9:"frequency";s:1:"2";s:7:"appears";
b:1;}s:8:"username";a:2:{s:9:"frequency";i:0;s:7:"appears";b:0;}}

Examples for json serialize results as

{"success":true,"email":{"lastseen":"2009-06-25 00:24:29","frequency":2,
"appears":true},"username":{"frequency":0,"appears":false}}

JSON Padding

We provide ajax/jquery support with JSONP, which allows for a callback function to be specified

myFunction({"success":true,"email":{"lastseen":"2009-06-25 00:24:29","frequency":2,
"appears":true},"username":{"frequency":0,"appears":false}})

Both serialized result examples have been line wrapped for readability but will be returned as a single line string

Based on a return of "yes", you can choose to deny registration. The lookup is case insensitive, too. Note that you will get an error message if your IP address or email address is improperly formatted.

See the section below for a more reliable method of scoring queries.


Confidence Scoring

We include a statistically calculated score, based on the last seen date and the number of sightings. This score is included by default in all serialized/XML data but not in a standard/legacy API call. If you wish to see this score using a legacy API call, please include this in your URL parameter list

&confidence

This confidence score is a reasonably good indicator that the field under test, would result in unwanted activity. The figure is a floating point score. Usage

http://www.stopforumspam.com/api?username=spammer&f=json

would respond with the result below, showing a confidence score on 31.64% likelihood of unwanted activity.

{"success":1,"username":{"lastseen":"2012-01-31 16:17:22","frequency":12,"appears":1,"confidence":31.64}}

wildcards

We operate a list of email domains, usernames and IP addresses that we personally consider dangerous. You may wish to ignore these lists, in which case you need to add the following URL parameters

To ignore the email/domain list checks, append

&nobademail

To ignore the username (partial string) list checks, append

&nobadusername

To ignore the IP lists (which includes some of the Internets most hostile spam friendly networks), append

&nobadip

To ignore all wildcard checks, append

&nobadall

Tor Exit Nodes

While Tor is a fantasic tool, it is open to abuse. Some site administrators way wish to accept traffic or registrations from Tor Exit nodes regardless of our listings.

Valid (good) Tor exit node IP addresses can be excluded by using the following parameter:

&notorexit

Encoding

Email and usernames should be "url encoded". In PHP, this can be done using the urlencode() function

If your default character encoding is not ISO-8859-1 or UTF8, it is very important that you convert the username to UTF8 before urlencode. This should be performed for submissions and API lookups. A PHP example

$username = urlencode(iconv('GBK', 'UTF-8', $username));

Date/Time format

Appending &unix to any query will return data/time results as UNIXTIME format, that being seconds since Unix epoc

Error Reporting

Any errors reported, within the control of the API, will be presented in the format specified when querying the API, in the following structure (here as json)

{"success":0,"error":"request not understood"}

DNSBL Queries

Our data is now shared with dnsbl.tornevall.org, please consider incorporating DNS checks first to reduce load on our server. Check their usage page for instructions.

Adding to the Database

Submissions to the database first require an API key. You can then use our add form to submit your spammer data. Please note that if you sign up on our forums with the same email address you used when you registered your API key, your key will be pre-populated in the form as long as you're logged in.

You can automate submissions by making an HTTP GET to the following URLs. We support different methods for submissions

Standard form submission can be done with the following parameters:

http://www.stopforumspam.com/add.php
?username=USERNAME
&ip_addr=IPADDRESS
&evidence=XXXXXXXXXX
&email=EMAILADDRESS
&api_key=ZZZZZZZZZZZZZZZ

Note: Username and Evidence fields must be converted to UTF-8 prior to submission. All fields must be urlencoded in order to preserve the correct details.

If required, data can be POSTed to the API, using the following example PHP code.

function PostToHost($data) {
   $fp = fsockopen("www.stopforumspam.com",80);
   fputs($fp, "POST /add.php HTTP/1.1\n" );
   fputs($fp, "Host: www.stopforumspam.com\n" );
   fputs($fp, "Content-type: application/x-www-form-urlencoded\n" );
   fputs($fp, "Content-length: ".strlen($data)."\n" );
   fputs($fp, "Connection: close\n\n" );
   fputs($fp, $data);
   fclose($fp);
}
PostToHost("username=USERNAME&ip_addr=IPADDRESS&email=EMAILADDRESS&api_key=XXXXXXXXXXXXX&evidence=YYYYYYYYYY");

Other platforms will require different code. Some PHP servers do not support socket connections, so please investigate this before implementing a solution

To verify, check the HTTP status code returned. a 200 will indicate a successful submission, whereas a 403 will indicate an unsuccessful attempt. A reason will be given (inside a paragraph tag) for unsuccessful attempts. Nothing will be returned for a successful submission.

Note that all information is required to submit (username, email, and IP address) however the evidence field can remain empty.

Terms

  • Your use of this data and supporting software is non-commercial.
  • You will not charge money for any software that utilizes the data.
  • API queries are limited to 20,000 per day.
  • Anything else is covered under a Creative Commons License
  • Any of the above terms may be waived, at the discretion, of the copyright holder (this website).
  • Hosting companies/providers have no permission to incorporate access to our data. This includes main-hosting.com (and all related companies)