From Halon, SMTP software for hosting providers
Revision as of 08:16, 3 March 2017 by Fredrik (Talk | contribs)

Jump to: navigation, search

The Halon SMTP software can be fully controlled using SOAP (Simple Object Access Protocol) which is an XML-based RPC-over-HTTP protocol. The system's (built-in, jailed) web administration is in fact connecting to the backend (control process) using SOAP.

Thus, it is possible to build your own interfaces and systems using the WSDL (Web Service Definition Language) file included on the appliance (https://your-appliance-ip/remote/?wsdl). Modern browser may show a styled version of the WSDL file using XSL at https://your-appliance-ip/remote/.

It is highly recommended to create a custom SOAP user with the system authentication script, and restrict access only to its intended SOAP functions (with the required permissions to operate).


Typically, HTTP basic authentication is used. However, If basic authentication is not supported in your SOAP client, the username and password may be passed using the query string:


Note: when passing username and password in the query string, be aware so that the username and password don't unintentionally end up in various log files/syslog (in proxies etc) before reaching the Halon.


Below are a few PHP examples. Begin by creating a SOAP client, that is used in all following examples.

$client = new SoapClient('',array(
'location' => '',
'uri' => 'urn:halon',
'login' => 'admin',
'password' => 'secretpassword'

Retrieve information about the three latest configuration revisions.

$items $client->configRevisionLog(array('limit' => 3))->result->item;

Search the message history, in this example the 50 latest messages to (according to the search filter syntax). The same parameters applies to mailQueue() for messages in quarantine and the outbound queue.

$items $client->mailHistory(array('filter' => '''offset' => '0''limit' => 50))->result->item;

An example how to extract statistical information.

$items $client->statList(array('key1' => 'hsl:stat''key2' => 'ip-family''key3' => 'ipv4'))->result->item;

An example how to get the current (running) configuration.

var_dump($client->configKeys()->result->item); // returns an array 

An example how to export the current (running) configuration.

var_dump($client->configCheckout()->result); // returns the plain-text configuration 

An example how to get a specific rate.

$client->hslRate(['ns' => 'foo''entry' => 'bar']); // returns an array 

An example how to add a domain with transport.

$domain '';
$transport '';

configPackArray($array) {
$result = array();
        foreach (
$array as $k => $v)
$result[] = array('first' => $k'second' => $v);

$args = array(
'mailserver'=> $transport,
$transport $client->configKeyAdd(array('key' => 'mail_transport''params' => configPackArray($args)));

$args = array(
$client->configKeyAdd(array('key' => 'mail_domain''params' => configPackArray($args))); 

Executing a command, such as statd.

$id $client->commandRun(array('argv'=> array('statd''-g''system-cpu-usage')));

try { 
true) {
$data $client->commandPoll(array('commandid' => $id->result));
                if (
} catch(
SoapFault $f) {} 

Export mail history as CSV, filter can be any Search filter.

$filter " or";
$items $client->mailHistory(array(
'filter' => $filter,
'offset' => '0',
'limit' => 10000))->result->item;
if (
is_array($items)) {
$out fopen('php://output''w');
    foreach (
$items as $item) {
fputcsv($out, array(
date('Y-m-d H:i:s',$item->msgts),
// var_dump($item);

Export license usage per domain.

$users $client->licenseUsers()->result->item;
$domains = [];
$longest 0;
if (
is_array($users)) foreach ($users as $user) {
$local$domain) = explode('@'$user);
$longest strlen($domain) > $longest strlen($domain) : $longest;
foreach (
$domains as $d => $c)