SOAP

From Halon, SMTP software for hosting providers
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).

Authentication

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:

https://your-appliance-ip/remote/?username=admin&password=secretpassword

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.

Examples

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

$client = new SoapClient('https://10.2.0.30/remote/?wsdl',array(
            
'features' => SOAP_SINGLE_ELEMENT_ARRAYS,
            
'location' => 'https://10.2.0.30/remote/',
            
'uri' => 'urn:halon',
            
'login' => 'admin',
            
'password' => 'secretpassword'
            
)); 

Retrieve information about the three latest configuration revisions.

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

Search the message history, in this example the 50 latest messages to admin@example.org (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' => 'to=admin@example.org''offset' => '0''limit' => 50))->result->item;
var_dump($items); 

An example how to extract statistical information.

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

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

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

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 'example.com';
$transport '1.1.1.1';

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

$args = array(
        
'active'=>'yes',
        
'hostname'=>'internal-hostname',
        
'mailserver'=> $transport,
        
'port'=>'25',
        
'retrydelay'=>'15,30,60,240',
        
'retrycount'=>'30',
        
'tls'=>'optional',
        
'sourceip'=>'auto',
        
'dsn'=>'yes',
        
'comment'=>'',
        
'script'=>'',
        
'mode'=>'inbound',
        
'sasluser'=>'',
        
'saslpass'=>'',
        
'prioqueue'=>'no'
);   
$transport $client->configKeyAdd(array('key' => 'mail_transport''params' => configPackArray($args)));

$args = array(
        
'active'=>'yes',
        
'name'=>'',
        
'domain'=>$domain,
        
'incoming'=>'mailserver:1',
        
'outgoing'=>'mailtransport:'.$transport->result,
        
'flow'=>'mailflow:1',
        
'tpl'=>'',
        
'rcptflow'=>'rcptflow:1'
);
$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 { 
        while(
true) {
                
$data $client->commandPoll(array('commandid' => $id->result));
                if (
$data->result->item)
                        echo 
implode(''$data->result->item);
        }
} catch(
SoapFault $f) {} 

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

$filter "from=user@example.org or to=user@example.com";
$items $client->mailHistory(array(
            
'filter' => $filter,
            
'offset' => '0',
            
'limit' => 10000))->result->item;
if (
is_array($items)) {
    
date_default_timezone_set('GMT0');
    
$out fopen('php://output''w');
    foreach (
$items as $item) {
        
fputcsv($out, array(
                    
date('Y-m-d H:i:s',$item->msgts),
                    
$item->msgaction,
                    
$item->msgfromserver,
                    
$item->msgfrom,
                    
$item->msgto,
                    
$item->msgsubject,    
                    ));
        
// var_dump($item);
    
}
    
fclose($out);