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.
The status page for site operators can be automatically opened from a link:
https://sblam.com/key.html?autologin=apikeyhash:time:sigwhere:
^&$@$2\n” + API key + “@@” (\n means a single line feed byte.)
time()+3600.
For example autologin value valid until 13.12.2007 14:19:27 for the key “abc123abc123” should be:
b7fc0a3373502b96f23c0cae099993d2:1197555567:e65ca523a9c8d687be2ebddbb86869f4Fetch content from https://sblam.com/keygen.html
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| Field names (keys) | Description (values) |
|---|---|
| uid | fixed server (website) identifier, which is secret. It can be any string, but it must be unique for each site and never change. |
| uri | Request path that received the post (e.g. “/cgi-bin/form.cgi”. It's usually known as REQUEST_URI) |
| host | Server's hostname (e.g. “example.com”. Usually HTTP_HOST or SERVER_NAME) |
| ip | Sender's IP (as text, e.g. “123.123.123.123” or IPv6 “[2a01:4ff:66:f5aa:11:0:1]”) |
| time | Current 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 |
| sblamcookie | Content of a cookie named “sblam_” |
| salt | Long random string |
| Field name | Description |
|---|---|
| field_0 | name of a form field which should contain the main content (e.g. “comment”) |
| field_1 | name of a form field which should contain author's name/signature (e.g. “author”) |
| field_2 | name of a form field which should contain author's e-mail (e.g. “e-mail”) |
| field_3 | name 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.
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\0Similarly 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: spambotHTTP_USER_AGENT\0spambot\0Send the data build as described above using POST method with the following HTTP header:
Content-Type:application/x-sblam;sig=XXXYYYor
Content-Type:application/x-sblam;sig=XXXYYY;compress=gzipif 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)
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:bb9c177510ba9219c75e0e02876c9c96The 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.