Spammer Slapper API Documentation

Please note that this is alpha grade software and the API can change at any moment. You will need a valid API key in order to use this product. You may request one from the home page

The Basics

The SpammerSlapper accepts GET or POST requests on port 80 at http://api.spammerslapper.com/check.php. The two required paramaters are:

• key: The API Key you recived
• package: A Base64 Encoded JSON String that contains query data and options as detailed.

The Query Data constists of the following (all are optional and by default empty):

• IP_ADDRESS: IP Address of the commentor, poster, the user who submited the form, etc...
• EMAIL_ADDRESS: The Email Address as entered by the user during submission or registration.
• MESSAGE: The actual message submitted, comment, post, etc...
• SUBJECT: The subject of the message submitted.
• USERNAME: The username or name used when submitting the message or registering an account.

The current options allow you to control which tests will run (by default all test will run except for CHECK_PROXY):

• CHECK_SPAMASSASIN: Runs a SpamAssasin test on the MESSAGE and SUBJECT.
• CHECK_PROXY: Checks if the user is submitting/registering behind a public proxy server.
• CHECK_HTTPBL: Queries the HTTP BL (Project Honeypot) to check if IP_ADDRESS is black listed for spamming.
• CHECK_FORUMSPAM: Queries the StopForumSpam database to check IP_ADDRESS, EMAIL_ADDRESS, and/or USERNAME
• CHECK_EMAIL: Checks to see if the email domain of the given address exists and accepts incomming mail
• CHECK_DBLORG: Searches all URL's in the MESSAGE and extracts domain names to check if any are listed in the local blacklist
• CHECK_SPAMHAUSDBL: Searches all URL's in the MESSAGE and extracts domain names to check if any are listed in the Spamhaus DBL

Submitting a Check Request

To submit a check, simply create a properly formated JSON string with the above query data and variables. Any values left out will fallback to the defaults. Encode the string in BASE64 and send it via POST or GET to http://api.spammerslapper.com/check.php. Be sure to include the key parameter, otherwise you'll get back an error. The POST method is recomended.

An example of a properly formated query string in JSON format before encoding in BASE64:

{"IP_ADDRESS":"8.8.8.8","EMAIL_ADDRESS":null,"MESSAGE":"Testing 1..2....3",
"SUBJECT":"Hello World","USERNAME":null,"CHECK_SPAMASSASIN":true,"CHECK_PROXY":false,
"CHECK_HTTPBL":true,"CHECK_FORUMSPAM":true,"CHECK_EMAIL":true,"CHECK_DBLORG":true,"CHECK_SPAMHAUSDBL":true}

Upon a sucessfull query, the server will respond back with another JSON string in plain text (not encoded in BASE64). This contains the results of the SPAM check.

{"SPAM":false,"Message":"","Reason":"","Details":[],
"Tests":["SPAMASSASIN","HTTPBL","FORUMSPAM","EMAIL","CHECK_DBLORG","CHECK_SPAMHAUSDBL"]}

The return values are explained below:

• SPAM: A boolean variables specifing whether the check came back as SPAM. True = yes, it was SPAM. False = no, not SPAM
• Message: A short message as to what happened, this message can be echoed to the user.
• Reason: Shows the test that failed (the test that idendified the check as SPAM).
• Details: An array that contains the failed test data, the contents vary across tests. Most of the time this will contain the test's score. For the PROXY test, it will contain the port number that the proxy was detected on.
• Tests: List of the tests applied during this query.

PHP Library

SpammerSlapper has made available an easy to use PHP library that can be used during your server side processing scripts. The library is available from this website. Below is a simple example that will just check the IP address with all default testing options.

    require('spammerslapperlib.php');
    $result = spammerslapper_check('XXXXXXAPI_KEYXXXXXXX');
    if($result->SPAM){
      //Code for faluire goes here
      die($result->Message);
    }
    else {
      //Code for success can go here.
    }

Download the SpammerSlapper PHP Library here.

The spammerslapper_check() function accepts two additional paramaters as arrays. The first is an array contiaining additional data to check, such as message text, message subject, email address, username, and an override to the automaticly detected IP address. NOTE: unused items can be omitted.

  $data = array(
    'message' => 'Testing 1...2...3',
    'subject' => 'Hello World',
    'emailAddress' => 'nobody@nowhere.tld',
    'username' => 'someone',
    'remoteAddress' => '8.8.8.8',
  );

The second array contains options to override the defaults. NOTE: default options can be omitted.

  $options = array(
    'CHECK_SPAMASSASIN' => false,
    'CHECK_PROXY' => true,
    'CHECK_HTTPBL' => true,
    'CHECK_FORUMSPAM' => true,
    'CHECK_EMAIL' => false
    'CHECK_DBLORG' => false
    'CHECK_SPAMHAUSDBL' => false
  );

To use the extra check data and additional options, just pass the paramaters like shown:

$result = spammerslapper_check('XXXXXXAPI_KEYXXXXXXX', $data, $options);

The SpammerSlapperResult object contains additional usefull information:

• SPAM: A boolean variables specifing whether the check came back as SPAM. True = yes, it was SPAM. False = no, not SPAM
• Message: A short message as to what happened, this message can be echoed to the user.
• Reason: Shows the test that failed (the test that idendified the check as SPAM).
• Details: An array that contains the failed test data, the contents vary across tests. Most of the time this will contain the test's score. For the PROXY test, it will contain the port number that the proxy was detected on.
• Tests: List of the tests ran during this query. The last test will always be the failed test, the others will be tests that passed.

Download the SpammerSlapper PHP Library here.

Want a button for your site? Click HERE to get one.