Sblam!

Spam filter for web forms

This is API documentation for developers of new Sblam! plugins. If you only want to integrate with an existing PHP website see install instructions for the existing plug-ins.

Auto login

The status page for site operators can be automatically opened from a link:

https://sblam.com/key.html?autologin=apikeyhash:time:sig

where:

  • apikeyhash is an MD5 hash (32 hex chars) of the string: “^&$@$2\n” + API key + “@@” (\n means a single line feed byte.)
  • time is unix timestamp when the link expires. It must be in the future. Use something like time()+3600.
  • sig is an MD5 hash of time + API key.

For example autologin value valid until 13.12.2007 14:19:27 for the key “abc123abc123” should be:

b7fc0a3373502b96f23c0cae099993d2:1197555567:e65ca523a9c8d687be2ebddbb86869f4

Getting new API keys

Fetch content from https://sblam.com/keygen.html

Server API

Server uses custom binary API and custom HTTP headers. The client must send HTTP POST in this special format.

Data is sent as pairs of keys and values. Keys and values are all separated with NUL bytes (\0) and strings are encoded in UTF-8. POST content looks something like that:

key1\0value1\0key2\0value2\0

Data to send

Required fields
Field names (keys)Description (values)
uidfixed server (website) identifier, which is secret. It can be any string, but it must be unique for each site and never change.
uriRequest path that received the post (e.g. “/cgi-bin/form.cgi”. It's usually known as REQUEST_URI)
hostServer's hostname (e.g. “example.com”. Usually HTTP_HOST or SERVER_NAME)
ipSender's IP (as text, e.g. “123.123.123.123” or IPv6 “[2a01:4ff:66:f5aa:11:0:1]”)
timeCurrent time as unix timestamp (e.g. string “1187543533”)
cookies“1” if sender has sent cookies, “0” otherwise
session“1” if the sender has been seen before, “0” if that's the first time they contacted your site
sblamcookieContent of a cookie named “sblam_”
saltLong random string
Optional fields
Field nameDescription
field_0name of a form field which should contain the main content (e.g. “comment”)
field_1name of a form field which should contain author's name/signature (e.g. “author”)
field_2name of a form field which should contain author's e-mail (e.g. “e-mail”)
field_3name of a form field which should contain a URL given by the post's author (e.g. “website”)

Fields field_X are supposed to contain names of actual form fields, not their content. It's OK to send empty string instead of the name, which means that the form doesn't have the corresponding field at all.

If the fields field_X are not set at all, then the server will try to guess using common default names.

Forwarding of the form data

You should send to Sblam! all form fields posted by the user (with exception of password fields and other sensitive data).

Key for each form field has prefix POST_. If there are multiple instances of a field with the same name, then concatenate them all together.

<textarea name="fieldname">content</textarea>
POST_fieldname\0content\0

Similarly forward all HTTP headers, except Cookie and Authorization. Their names should be normalised the same way CGI does: with HTTP_ prefix, all uppercase and with “-” replaced with “_”.

User-Agent: spambot
HTTP_USER_AGENT\0spambot\0

Sending to the server

Send the data build as described above using POST method with the following HTTP header:

Content-Type:application/x-sblam;sig=XXXYYY

or

Content-Type:application/x-sblam;sig=XXXYYY;compress=gzip

if you're going to gzip-compress the payload.

The XXX is an MD5 hash (32 hex chars) of the string: “^&$@$2\n” + API key + “@@” (and \n means single byte line feed).

md5("^&$@$2\ndefault@@"); // for the API key “default”

YYY is an MD5 hash of API key + entire payload (if the data is compressed, the hash is after compression)

Server answer

If status is different than 200, then the error message is in the HTTP status line and the response body is meaningless.

If server responds with status 200, then body of the response will contain colon-separated fields:

-1:2a6d8fa0d:bb9c177510ba9219c75e0e02876c9c96
  • Filtering result (described in the manual) (-2, -1 = Ham, 0 = unknown, 1, 2 = Spam).
  • ID of the post that can be used to report filter's mistake (if it's empty or “0” it means the post hasn't been accepted by the server). Filter's mistakes can be reported by users at: https://sblam.com/report/this identifier
  • MD5 hash of: API key + filtering result + the “salt” field from data submitted to the server. You can verify this hash to ensure data integrity.

Optional client-side JavaScript

The standard PHP plugin comes with a bit of PHP-generated JavaScript. I'm not documenting it, since it's very simple. Just look at the source and convert it to your language of choice, if necessary.