Kerio Connect API

The Kerio Connect API enables you to programmatically access your Kerio Connect server to integrate with third-party solutions or write scripts to automate specific tasks. The API provides all actions available in the client and administration interfaces of the product. For example, you can add/remove users, update IP addressAn identifier assigned to devices connected to a TCP/IP network. groups, read logs, manage time ranges, and much more.

Licensing

The API is part of Kerio Connect and is governed by the product’s license. In summary, the license to use Kerio Connect also entitles you to use the API on your server. Third-party software vendors may distribute their applications both for free or for profit. There is no royalty fee for using the API.

Get involved

A dedicated forum is available for sharing your ideas, questions, answers, and other feedback with the developer community. You can participate in the forum at forums.kerio.com.

Introduction

The API is accessible via a secure, session based HTTPHypertext Transfer Protocol - A protocol for exchange of hypertext documents in HTML. connection. All communication is formatted as a JSON string and directed to a designated URLUniform Resource Locator is the address of a web page on the world wide web.. For example, a request for the Kerio Connect administration API may go to:

https://server.example.com:4040/admin/api/jsonrpc/

The URL to access the API consists of the following parts:

URL part	Title	Description
https://	Protocol	The API uses HTTPSSecure version of secured by SSL.
server.example.com	Hostname	The Internet accessible hostname (domain name) of your server
:4040	Port	The port number for accessing the API
/admin/api/jsonrpc/	File path	The file path of the JSON interface

You can learn more about the composition of a URL through the Mozilla Foundation documentation.

The Kerio Connect API is accessible via two separate interfaces that provide different functionality. The Kerio Connect client interface provides email and messaging functionality such as composing email, creating an out of office message, or managing mail filter rules. The Kerio Connect Administration interface configures all server based functionality such as adding users, managing mailing lists, or configuring domains. The port number and file path vary depending on the interface.

Refer to the table below:

Product interface	Port	File path
Kerio Connect client	443	/webmail/api/jsonrpc/
Kerio Connect Administration	4040	/admin/api/jsonrpc/

Prerequisites

To access the API, you need a Kerio Connect user account. Depending on the interface, this may be a standard user account, or an administrator account with elevated permissions. The type of account you use to authenticate determines your permissions when accessing the API. In order to communicate with the API you need a framework for processing the requests and managing the network connection. A common framework for these actions is PHP and cURL.

Authentication

The API uses a two step authentication process. The first authentication step involves a username and password, the same type of account used to access the Kerio Connect interface. After successful authentication, the API returns a randomized token, and a session cookie. All subsequent requests to the API must include the token and session cookie in the HTTP headers of the connection. The method for handling the session cookie and token depends on the framework used in your application. Refer to the example below for information on how you can manage authentication to the API using cURL.

API Requests

All requests to the API must be encoded as a JSON string. The JSON string is an array consisting of the JSON version, an identifier, the API method, and the parameters of the query. You can use a web browser to inspect the JSON request and response for any interaction with the product interface. Refer to Inspecting the Kerio Connect API communication in a web browser for details.

Example API Communication

The following example uses PHP and cURL to get the total number of mailbox accounts.

$api_cookie = "/tmp/kerio-api-cookie";
$api_url = "https://connect.example.com:4040/admin/api/jsonrpc/";
$api_user = "admin-api";
$api_password = "secretpassword”;

//Initialize the cURL request
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $api_url);
curl_setopt($ch, CURLOPT_HTTPHEADER, "Content-Type:application/json");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_SSLSecure Sockets Layer -  A protocol that ensures integral and secure communication between networks._VERIFYHOST, false);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_COOKIEJAR, $api_cookie);
curl_setopt($ch, CURLOPT_COOKIEFILE, $api_cookie);

//Server login request to obtain the API token and session cookie
$api_login = array(
'jsonrpc' => '2.0',
'id' => 1,
'method' => 'Session.login',
'params' => array(
	'userName' => $api_user,
	'password' => $api_password,
	'application' => array(
		'name' => 'Sample app',
		'vendor' => 'Kerio',
		'version' => '1.0'
		)
	)
);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($api_login));
$return = json_decode(curl_exec($ch), true);
$token = $return['result']['token'];

//Verify the token, otherwise return the JSON response and exit the script.
if ($token == "") {
	printf(htmlspecialchars($json_return));
	exit();
}

//Add the token to the cURL headers
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Content-Type:application/json", "X-Token:".$token));

//Get the total mailbox count
$api_query = array(
	'jsonrpc' => '2.0',
	'id' => '1',
	'method' => 'Users.getMailboxCount',
'params' => array()
);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($api_query));
$return = json_decode(curl_exec($ch), true);
$mailbox_count = $return['result'][total];

curl_close($ch);