If XML-RPC is enabled, an external program written in many different programming languages can communicate with POPFile to use its services. The POPFile API is exposed via the UI::XMLRPC module which was first shipped with the 0.22.0 release. The UI::XMLRPC module requires some extra Perl components not used by a standard POPFile installation.

Full details of the API and methods can be found here: popfile_xml-rpc_api

General information about XML-RPC can be found here: XMLRPC.com

The Windows installer offers the UI::XMLRPC module as an optional component (it is not part of the default installation). When the optional UI::XMLRPC module is installed, the Windows installer will also install the extra Perl components the module requires.

Your XMLRPC client can be run on any machine and can be written in any language. The client is not supplied, you must supply your own. Sample Perl, Python, Delphi and NSBasic/CE clients are provided below.

Listen Port

The XML-RPC listen port can be configured on POPFile's Configuration page in the Module Options section. Note that the configuration option will not be displayed unless the UI::XMLRPC.pm module is installed and POPFile has been restarted to recognize the module's presence.


When installed, the module will add a new security option to the POPFile UI's Security Page under the server section. The option “Accept XML-RPC connections from remote machines (requires POPFile restart)” will appear. To permit access from non-localhost machines, you must set this option to yes.

Required Perl Modules

Note: If you use the Windows installer to install the UI::XMLRPC module then these Perl components will automatically be installed for you.

The following Perl modules must be installed on the machine running POPFile. Additionally, the SOAP::Lite module would be required on any client machine using a Perl client to access POPFile via XMLRPC.

  • XMLRPC.pm must be installed to your UI directory of POPFile's installation directory. You can obtain it from CVS here, make sure to save it with the filename XMLRPC.pm. POPFile must be restarted to recognize the module.
  • SOAP::Lite which includes XMLRPC::Lite must be installed to use the XML-RPC features. The SOAP::Lite module can be obtained from CPAN. If using Activestate Perl it can be installed from ppm, e.g.,
   >install SOAP-Lite

Sample Code

Simple Examples

Perl Example 1

use strict;
use XMLRPC::Lite;
my $sk = XMLRPC::Lite ->proxy('http://localhost:8081/RPC2')
         -> call('POPFile/API.get_session_key','admin', '')
         -> result;
print XMLRPC::Lite ->proxy('http://localhost:8081/RPC2')
      -> call('POPFile/API.classify',$sk,'spam.txt')
      -> result;
XMLRPC::Lite ->proxy('http://localhost:8081/RPC2')
      -> call('POPFile/API.release_session_key',$sk);

Saving the above as testxml.pl and running it with test message 'spam.txt' with a properly configured system will result in the following output:

perl testxml.pl

Python Example 1

from xmlrpclib import ServerProxy
POPFile = ServerProxy("http://localhost:8081")
pf = POPFile.POPFile.API	# naming shortcut to make things easier
key = pf.get_session_key("admin","")
print pf.classify(key, "spam.txt")

Saving the above as testxml.py and running it with test message 'spam.txt' with a properly configured system will result in the following output:

   python testxml.py

Delphi Example

program popdelphi;
  sysutils, xmlrpctypes, xmlrpcclient;
  caller: TCaller;
  func: TFunction;
  rslt: TResult;
  SessionKey: String;
  MessageBucket: String;
  caller := TCaller.Create;
  caller.EndPoint := '/RPC2';
  caller.HostName := '';
  caller.HostPort := 8081;
  func := TFunction.Create;
  func.ObjectMethod := 'POPFile/API.get_session_key';
  rslt := caller.Execute(func);
  SessionKey := rslt.GetString;
  func.ObjectMethod := 'POPFile/API.classify';
  rslt := caller.Execute(func);
  MessageBucket := rslt.GetString;
  func.ObjectMethod := 'POPFile/API.release_session_key';

This implementation uses xmlrpctypes and xmlrpcclient which are available in Delphi XML-RPC library. You will also need Indy - Internet Direct Components.

Saving and compiling the above will create popdelphi.exe. Running it in a DOS prompt (a default path would be interesting), passing a message file name as argument and using a properly configured system, will result in the following output example:

   popdelphi popfile99.msg

NSBasic/CE for Windows CE Example

 AddObject "PocketXMLRPC.Factory","xmlrpc"
 Set popfile = xmlrpc.proxy("","POPFile/API.")
 sessionKey = popfile.get_session_key("admin", "")
 message = MsgBox("POPFile Session Key is " & sessionKey, vbInformation, "POPFile Message")
 Print popfile.classify(sessionKey,"C:\spam.txt")

This implementation uses NS Basic/CE for Windows CE. You will also need PocketHTTP and PocketXML-RPC COM components.

Remember that, in this example, you are not accessing localhost, you are outside your POPFile default installation. So, you will need to point your mobile device to a valid network IP where your POPFile is running. In this case, is the desktop IP where POPFile is running. Your mobile device will be accessing XMLRPC interface via bluetooth network or WiFI. Considering that, you will also need to Accept XML-RPC connections from remote machines. This may be done using Security tab and setting this feature to Yes.

Advanced Examples

Advanced Perl 1 (More Complex with Error Checking)

use strict;
use XMLRPC::Lite;
my $xml= XMLRPC::Lite
   -> proxy('http://localhost:8081/RPC2')->on_fault(sub{});
# Get a session key from POPFile
my $sk = $xml->call("POPFile/API.get_session_key",'admin','');
my $key = $sk->result;
my $method = "POPFile/API.$ARGV[0]";
my @params = @ARGV[1..10];
unshift @params,$key;
my $can = $xml->can($method);
my $res = eval {$xml->call($method,@params)};
if ($@) {
    print join("\n","syntax error: " ,$@);
} elsif ($can && !UNIVERSAL::isa($res => 'XMLRPC::SOM')) {
    print $res;
} elsif (defined($res) && $res->fault) {
    print join ("\n","XMLRPC FAULT: ", @{$res->fault}{'faultCode','faultString'});
} elsif (!$xml->transport->is_success) {
    print join ("\n","TRANSPORT ERROR: ", $xml->transport->status);  
} else  {
    if ( ref $res->paramsall eq 'ARRAY' ) {
        print join "\n", @{$res->paramsall};
    } else {
        print $res->paramsall;
print "\n";
# Release the session key
# All Done

Saving the above as testxml.pl and running it with commandline parameters shown returns the result of the API call.

   perl testxml.pl get_bucket_parameter spam count

   perl testxml.pl get_bucket_parameter spam fpcount

   perl testxml.pl get_bucket_parameter spam fncount

   perl testxml.pl get_bucket_color spam

   perl testxml.pl get_bucket_word_count spam

   perl testxml.pl get_bucket_unique_count spam

   perl testxml.pl get_buckets

Advanced Perl 2

Implement pipe.pl as an XMLRPC client

use strict;
use XMLRPC::Lite;
# we want secure temporary files, though this script will usually be run as a user
use File::Temp qw/tempfile tempdir/;
# a folder we can access that will go away when we exit
my $temp_dir = tempdir( CLEANUP => 1);
# and a temporary file, with the full path specified
my ($fh_in, $filename_in) 
    = tempfile('popfileinXXXXXXX', SUFFIX => ".msg", UNLINK => 1 , DIR => $temp_dir);
# act like a pipe, reading from STDIN
while (<STDIN>) {
	print $fh_in $_;
# POPFile expects a closed file
close $fh_in;
# create a secure output file
my ($fh_out, $filename_out) 
   = tempfile('popfileoutXXXXXXX', SUFFIX => ".msg", UNLINK => 1, DIR => $temp_dir);
# our XMLRPC proxy
my $xmlrpc = XMLRPC::Lite ->proxy('http://localhost:8086/RPC2');
# say hello and get a session key
my $sk = $xmlrpc-> call('POPFile/API.get_session_key','admin','')
		-> result;
# this does the work		
$xmlrpc-> call('POPFile/API.handle_message',$sk,$filename_in,$filename_out)
		-> result;
# say goodbye
$xmlrpc-> call('POPFile/API.release_session_key',$sk);
# continue acting like a pipe, and print to STDOUT
while (<$fh_out>) {
	print $_;
# exit, and File::Temp cleans up


Full access to POPFile's API (declared in POPFile::API module) through UI::XMLRPC module. For further documentation on API syntax, see the Classifier::Bayes module that ships with POPFile.

Note that you must obtain a session_key using the get_session_key API call in order to use any of the API's. You should release the key using release_session_key when you are finished.

The XML-RPC available methods are:

Subroutine NameUsage comments

returns a session_key


releases the session key

call('POPFile/API.classify', 'session_key', 'filename')

returns bucket name, note that filename must exist in the popfile directory (or the full path must be specified) on the machine that is running POPFile.

classify_and_modifyDoes not work for XmlRpc, expects filehandles, use handle_message instead.
call('POPFile/API.handle_message', 'session_key', 'inputfilename', 'outputfilename')

returns bucketname, the history slot-id, and a Boolean specifying whether a magnet was used for classification, similar to classify but adds message to POPFile history and writes message with POPFile headers to output file. Note, there is a known issue with this call. It presently adds a . and 0x0d0a to the end of output file.


returns an array of bucket names (exclude 'unclassified' bucket)


returns an array of pseudo-bucket names ('unclassified' bucket)


returns an array of bucket names (include 'unclassified' bucket)

call('POPFile/API.is_bucket','session_key', 'bucketname')

returns 1 if the bucketname exists, returns 0 if the bucketname does not exist, or the bucketname is a pseudo-bucket ('unclassified' bucket)

call('POPFile/API.is_pseudo_bucket','session_key', 'bucketname')

returns 1 if the bucketname exists and it is a pseudo-bucket ('unclassified' bucket), returns 0 if the bucketname does not exist, or the bucketname is not a pseudo-bucket

call('POPFile/API.get_bucket_word_count', 'session_key', 'bucketname')

returns word count of bucket

call('POPFile/API.get_bucket_word_list', 'session_key', 'bucketname')

returns array of words found in bucket

call('POPFile/API.get_bucket_word_prefixes', 'session_key', 'bucketname')

returns array of initial letters for words found in bucket

call('POPFile/API.get_cont_for_word', 'session_key', 'bucketname', 'someword')

returns word count for someword in bucket


returns word count of all buckets combined

call('POPFile/API.get_bucket_unique_count', 'session_key', 'bucketname')

returns unique words in bucket

call('POPFile/API.get_bucket_color', 'session_key', 'bucketname')

returns color as string. Note: this API is DEPRECATED in favor of calling get_bucket_parameter for the parameter named 'color'

call('POPFile/API.set_bucket_color', 'session_key', 'bucketname', 'colorstring')

set the color of bucket. Returns 1 if succeeded. Note: this API is DEPRECATED in favor of calling set_bucket_parameter for the parameter named 'color'

call('POPFile/API.get_bucket_parameter', 'session_key', 'bucketname', 'parameter')

returns parameter value. Parameter can be one of count (classification count), fpcount (false positives), fncount (false negatives), subject (subject header modification), xtc (X-Text-Classification header), xpl (X-POPFile-Link header), quarantine (quarantine messages), or color (bucket color)

call('POPFile/API.set_bucket_parameter', 'session_key', 'bucketname', 'parameter', 'value')

sets the parameter to value, returns 1 if succeeded. Parameter can be one of count (classification count), fpcount (false positives), fncount (false negatives), subject (subject header modification), xtc (X-Text-Classification header), xpl (X-POPFile-Link header), quarantine (quarantine messages), or color (bucket color)

get_html_colored_messageNote: get_html_colored_message was accidently left out of 0.22 but has been back in 0.22.1.
call('POPFile/API.get_html_colored_message', 'session_key', 'filename')

returns string containing colored message, note that filename must exist in the popfile directory or the full path must be specified

call('POPFile/API.create_bucket', 'session_key', 'bucketname')

returns 1 if succeeded

call('POPFile/API.delete_bucket', 'session_key', 'bucketname')

returns 1 if succeeded. Note that you cannot delete 'unclassified' bucket

call('POPFile/API.rename_bucket', 'session_key', 'bucketname', 'newname')

returns 0 on failure, 1 on success

call('POPFile/API.add_message_to_bucket', 'session_key', 'bucketname', 'filename')

Train POPFile with a mail file (reclassify a mail file to bucketname). Returns 0 on failure, 1 on success, note that filename must exist in the popfile directory or the full path must be specified

call('POPFile/API.add_messages_to_bucket', 'session_key', 'bucketname', 'filelist')

Train POPFile with mail files (reclassify mail files to bucketname). Returns 0 on failure, 1 on success, note that filenames must exist in the popfile directory or the full path must be specified

call('POPFile/API.remove_message_from_bucket', 'session_key', 'bucketname', 'filename')

Undo training POPFile. Returns 0 on failure, 1 on success, note that filename must exist in the popfile directory or the full path must be specified

call('POPFile/API.magnet_count', 'session_key')

returns magnet count of all bucket combined

call('POPFile/API.get_buckets_with_magnets', 'session_key')

returns array of bucket names specified by any magnets

call('POPFile/API.get_magnet_types_in_bucket', 'session_key', 'bucketname')

returns array of magnet types for the bucket

call('POPFile/API.clear_bucket', 'session_key', 'bucketname')

empties the bucket. Returns 1 if succeeded


removes all magnets. Returns 1 if succeeded

call('POPFile/API.get_magnets', 'session_key', 'bucketname', 'type')

returns array of magnets of the specified type for the bucket

call('POPFile/API.create_magnet', 'session_key', 'bucketname', 'magnettype', 'magnetvalue')

creates a new magnet. Returns 1 if succeeded


returns a hash list of valid POPFile magnet types and mail headers

call('POPFile/API.delete_magnet', 'session_key', 'bucketname', 'magnettype','magnetvalue')

deletes the magnet. Returns 1 if succeeded


returns array of stop words

call('POPFile/API.add_stopword', 'session_key', 'mystopword')

adds a word to stop words. Returns 0 if failed, 1 if succeeded

call('POPFile/API.remove_stopword', 'session_key', 'mystopword')

removes a word from stop words. Returns 0 if failed, 1 if succeeded

Note: In the API calls above, the 'session_key' is the key that is returned to you by the API call get_session_key.

For older versions of POPFile please replace “POPFile/API.” with “Classifier/Bayes.”.

popfilemodules/xmlrpc.txt · Last modified: 2010/09/09 19:46 by amatubu

Should you find anything in the documentation that is incomplete, unclear, outdated or just plain wrong, please let us know and leave a note in the Documentation Forum.

Recent changes RSS feed Donate Driven by DokuWiki
The content of this wiki is protected by the GNU Fee Documentation License