Please NOTE - This documentation refers to the deprecated obsolete v1.0 API, you should prefer the v2.0 API.

This API will no longer be available after the 1st January 2015.

testComment

The testComment function of our API allows you to test whether a submitted comment is SPAM or not.

The Input Paramater

The testComment function accepts a single parameter, which is an XML::RPC struct. (XML-RPC mandates the format of several parameter types such as "string", "int", "struct". In this case consider a "struct" analagous to a perl hash or a PHP array).

The structure you pass may have the following members. Members which are not recognised will be ignored.

NameDescription
commentThe body of the submitted comment.required
ipThe IP address the comment was submitted from.required
agentThe user-agent the submitter supplied.
emailThe email address the submitter supplied.
linkThe homepage link the submitter supplied.
nameThe name the submitter supplied.
optionsAdditional options to control how things should work.
siteA link to your site - this parameter is needed for the getStats() function to be useful.
subjectThe subject/title the submitter supplied.
versionThe version of the plugin that you're using, if any.

The Return Value

The return value of the function call is a single string. This string will contain one of three values:

ERROR:[message]There was a fatal error during the processing of your request.
OK:[message]The submitted content was judged to be non-spam.
SPAM:[reason]The submitted content was judged to be spam.

The results may return an optional reason, separated by a colon (:) character (if there is no reason the colon will still be present). This extra detail might be missing, but if present should provide useful diagnostic information.

If you receive a timeout, or other transient failure, it is up to you to decide how to handle this. Personally if I were coding a new plugin I'd simply allow the comment - rather than retrying.

Customizing The Testing

In the input parameter table above you'll notice there is an "options" parameter. You may submit a number of flags in this field to affect the testing of your submitted comment.

Set the value of this parameter to a comma-separated string - with the following possible components:

NameDescriptionDefault
blacklist=1.2.3.4Blacklist the given IP (*)
exclude=fooDon't run the plugin test "foo" (**)
failIf you pass this option your query will always return a SPAM result.
Useful for testing.
whitelist=1.2.3.4Whitelist the given IP (*)
mandatory=subject Specify that the given field should always be present.
See the table on above for valid field names.
max-links=5The comment body must contain fewer than 5 links10
max-size=2kThe comment body must be smaller than 2k to be approved.
min-size=2kThe comment body must be at least 2k to be approved.
min-words=10The comment body must contain at least 10 words to be approved.4

Multiple Values

Values may be specified multiple times. For example you might wish to blacklist the two IP addresses 1.2.3.4 and 8.7.6.5 This could be done by passing an "options" string of:

blacklist=1.2.3.4,blacklist=8.7.6.5

[*] - You may use either a literal IP address ("192.168.1.1") or a CIDR range ("192.168.1.0/8").

[**] - You can find the list of plugin names via calling the getPlugins method, or looking at our source code.