/ 
Blog-Spam-0.3
/ Blog::Spam::API

NAME

Blog::Spam::Server - A description of the XML-RPC API.

ABOUT

This document discusses the API which is presented by the Blog::Spam::Server. This API is exposed via XML-RPC such that it may be called by remote locations.

XML-RPC METHODS

The Blog::Spam::Server exposes several methods to clients from remote locations. The following methods are documented:

testComment This is the method which is used to test a submitted comment from a blog or server.
getPlugins This returns the names of the internal plugins we use - it is used such that a remote machine may selectively disable some of them.
getStats Return the statistics for SPAM detection for a given domain.
classifyComment This allows a limited amount of re-training for a submitted comment.

Each of these methods will be discussed in order of important, and additional documentation is available online via http://api.blogspam.net/

API

testComment

The testComment method has the following XML-RPC signature:

string testComment( struct );

(This means the method takes a "struct" as an argument, and returns a string. In perl terms the struct is a hash.)

When calling this method you should pass the following parameters to the method:

agent   - The user-agent of the submitting browser, if any.
comment - The body of the comment
email   - The email address submitted
ip      - The IP the comment was submitted from.
name    - The name the user chose, if any.

options - Discussed later, see "TESTING OPTIONS".

The only mandatory arguments are "comment" and "IP", the rest are optional but may be useful and it is recommended you pass them if you can.

The return value from this method will either be "OK", or "SPAM". Optionally a reason may be returned in the case a comment is judged as SPAM, for example:

SPAM:I don't like comments submitted before 9AM.

classifyComment

The classifyComment method has the following XML-RPC signature:

string classifyComment( struct );

(This means the method takes a "struct" as an argument, and returns a string. In perl terms the struct is a hash.)

getPlugins

The getPlugins method has the following XML-RPC signature:

array getPlugins( );

(This means the method takes no arguments, and returns an array.)

getStats

The getStats method has the following XML-RPC signature:

struct getStats( string );

(This method returns a struct and takes a string as its only argument.)

TESTING OPTIONS

You may pass the optional "options" string to the server, if you wish finer control.

This option string should consist of comma-separated tokens.

The permissible values are:

whitelist=1.2.3.0/24    - Whitelist the given IP / CIDR range.
blacklist=1.2.3.3/28    - Blacklist the given IP / CIDR range.

exclude=plugin          - Don't run the plugin with name "plugin".

mandatory=subject,email - Specify the given field should always be
                          present.

max-links=20            - The maximum number of URLs.

min-size=1024           - Minimum body size.

max-size=2k             - Maximum body size

fail                    - Always return "spam"

These options may be repeated, for example the following is a valid value for the "options" setting:

mandatory=subject,mandatory=name,whitelist=1.2.3.4,exclude=surbl

That example will:

1. Make the "subject" field mandatory.

2. Makes the "name" field mandatory.

3. Whitelists any comments subitted from the IP 1.2.3.4

4. Causes the server to not run the surbl test.

LICENSE

This code is licensed under the terms of the GNU General Public License, version 2. See included file GPL-2 for details.

AUTHOR

Steve -- http://www.steve.org.uk/

LICENSE

Copyright (c) 2008-2010 by Steve Kemp. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The LICENSE file contains the full text of the license.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 132:

=cut found outside a pod block. Skipping to next block.