From Halon, SMTP software for hosting providers
Revision as of 12:26, 16 June 2017 by Fredrik (talk | contribs) (Examples)
Jump to: navigation, search

The Halon platform 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 [email protected] (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' => '[email protected]''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 

Export the current (running) configuration

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

Get a specific rate

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

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 "[email protected] or [email protected]";
$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)

Read from a file (tailing)

$read $client->fileRead(['file' => '/storage/log/mail.log''offset' => -1'size' => 0]);
while (
$read $client->fileRead(['file' => '/storage/log/mail.log''offset' => $read->offset'size' => 8192]);
    if (

Deleting specific items from the HSL cache

$_POST['delete-item'] = 'true';
$_POST['ns'] = null;
$_POST['function'] = 'api_call_http';

$_POST['argument'][1] = '1';
$_POST['type'][1] = 'string';
$_POST['value'][1] = 'test';

$_POST['argument'][2] = 2;
$_POST['type'][2] = 'json';
$_POST['value'][2] = '[""]';

if (isset($_POST['delete-item']))
$item = [];
    if (
$item['ns'] = $_POST['ns'];
    if (
$item['function'] = $_POST['function'];
    if (
$item['arguments'] = [];
    foreach (
$_POST['argument'] as $k => $i)
$type $_POST['type'][$k];
        if (
$type == 'json')
$data $_POST['value'][$k];
        if (
$type == 'string')
$data json_encode($_POST['value'][$k]);
$item['arguments'][] = ['index' => $i'value' => $data];