Sample API Communication

A working example which guides you through the API basics. It prints a list of all available domains.

To make it work, please follow these steps:

1. Login

Login includes entering server hostname and login credentials with administration rights.

Request

POST /admin/api/jsonrpc/ HTTP/1.1
Accept: application/json-rpc
Content-Type: application/json-rpc; charset=UTF-8
User-Agent: Kerio APIs Client Library for PHP/1.3
Host: mail.company.tld:4040
Content-Length: 217
Connection: close

{"jsonrpc":"2.0","id":1,"method":"Session.login","params":{"userName":"admindemo","password":"readonly","application":{"name":"Example: Get all domains","vendor":"Kerio Technologies s.r.o.","version":"BUILD_HASH"}}}

Response

 HTTP/1.1 200 OK
Connection: Close
Content-Type: application/json-rpc; charset=utf-8
Date: Thu, 28 Aug 2014 06:46:32 GMT
Server: Kerio Connect 8.3.1
X-Frame-Options: SAMEORIGIN
X-UA-Compatible: IE=edge
Set-Cookie: SESSION_CONNECT_WEBADMIN=ff313031fce1015030d208542172d0bab257633bb1ff94f6fafb17be53f1415f; path=/admin/; secure; HttpOnly

{"jsonrpc":"2.0","id":1,"result":{"token":"661415af99698a00d9e2a3335350d0c27e14c032fe34c7c52d853e13908c6791"}}

It is also possible to use the read-only rights but please keep in mind that you cannot change any settings then.

2. CSRF Protection

Each request must contain valid Cookies with the X-Token value you obtained from login response.

3. Send a Request

To send a request, just send the JSON to server's API endpoint.

Request

POST /admin/api/jsonrpc/ HTTP/1.1
Accept: application/json-rpc
Content-Type: application/json-rpc; charset=UTF-8
User-Agent: Kerio APIs Client Library for PHP/1.3
Host: mail.company.tld:4040
Content-Length: 439
Connection: close
Cookie:  SESSION_CONNECT_WEBADMIN=ff313031fce1015030d208542172d0bab257633bb1ff94f6fafb17be53f1415f;
X-Token: 661415af99698a00d9e2a3335350d0c27e14c032fe34c7c52d853e13908c6791

{"jsonrpc":"2.0","id":3,"token":"661415af99698a00d9e2a3335350d0c27e14c032fe34c7c52d853e13908c6791","method":"Domains.get","params":{"query":{"fields":["id","name","description","aliasList","userMaxCount","outgoingMessageLimit","isPrimary","renameInfo","forwardingOptions","kerberosRealm","winNtName","ipAddressBind","pamRealm","keepForRecovery","isDistributed"],"start":0,"limit":-1,"orderBy":[{"columnName":"name","direction":"Asc"}]}}}

Response

HTTP/1.1 200 OK
Connection: Close
Content-Type: application/json-rpc; charset=utf-8
Date: Thu, 28 Aug 2014 06:46:35 GMT
Server: Kerio Connect 8.3.1
X-Frame-Options: SAMEORIGIN
X-UA-Compatible: IE=edge

{"jsonrpc":"2.0","id":3,"result":{"list":[{"id":"keriodb://domain/2cf3ef60-c3c3-492b-ab57-a9a8774bd7fc","name":"demo.kerio.com","description":"","isPrimary":true,"userMaxCount":0,"outgoingMessageLimit":{"isActive":false,"limit":{"value":0,"units":"Bytes"}},"keepForRecovery":{"isEnabled":true,"days":30},"aliasList":[],"forwardingOptions":{"isEnabled":false,"host":"","port":0,"how":"Online","preventLoop":false},"kerberosRealm":"DEMO.local","winNtName":"","pamRealm":"","ipAddressBind":{"enabled":false,"value":"0.0.0.0"},"renameInfo":{"isRenamed":false,"oldName":"","newName":""},"isDistributed":false},{"id":"keriodb://domain/5bbfeb95-e192-4fbb-84da-e4cbcde54ac8","name":"123.com","description":"","isPrimary":false,"userMaxCount":0,"outgoingMessageLimit":{"isActive":false,"limit":{"value":0,"units":"Bytes"}},"keepForRecovery":{"isEnabled":false,"days":0},"aliasList":[],"forwardingOptions":{"isEnabled":false,"host":"","port":0,"how":"Online","preventLoop":false},"kerberosRealm":"","winNtName":"","pamRealm":"","ipAddressBind":{"enabled":false,"value":"0.0.0.0"},"renameInfo":{"isRenamed":false,"oldName":"","newName":""},"isDistributed":false},{"id":"keriodb://domain/c21d1204-f65e-4628-8459-44668764ccc4","name":"abc.co.uk","description":"","isPrimary":false,"userMaxCount":0,"outgoingMessageLimit":{"isActive":false,"limit":{"value":0,"units":"Bytes"}},"keepForRecovery":{"isEnabled":false,"days":0},"aliasList":[],"forwardingOptions":{"isEnabled":false,"host":"","port":0,"how":"Online","preventLoop":false},"kerberosRealm":"","winNtName":"","pamRealm":"","ipAddressBind":{"enabled":false,"value":"0.0.0.0"},"renameInfo":{"isRenamed":false,"oldName":"","newName":""},"isDistributed":false},{"id":"keriodb://domain/4a4b2cd5-8b11-4bd6-8664-d0d659d28382","name":"dokimi.gr","description":"","isPrimary":false,"userMaxCount":0,"outgoingMessageLimit":{"isActive":false,"limit":{"value":0,"units":"Bytes"}},"keepForRecovery":{"isEnabled":false,"days":0},"aliasList":[],"forwardingOptions":{"isEnabled":false,"host":"","port":0,"how":"Online","preventLoop":false},"kerberosRealm":"","winNtName":"","pamRealm":"","ipAddressBind":{"enabled":false,"value":"0.0.0.0"},"renameInfo":{"isRenamed":false,"oldName":"","newName":""},"isDistributed":false},{"id":"keriodb://domain/2c23dc19-43a2-465f-86b5-8816bf53bbd4","name":"example.com","description":"","isPrimary":false,"userMaxCount":0,"outgoingMessageLimit":{"isActive":false,"limit":{"value":0,"units":"Bytes"}},"keepForRecovery":{"isEnabled":false,"days":0},"aliasList":[],"forwardingOptions":{"isEnabled":false,"host":"","port":0,"how":"Online","preventLoop":false},"kerberosRealm":"","winNtName":"","pamRealm":"","ipAddressBind":{"enabled":false,"value":"0.0.0.0"},"renameInfo":{"isRenamed":false,"oldName":"","newName":""},"isDistributed":false},{"id":"keriodb://domain/46a6c031-1cc3-4f9e-9734-25ab9d22e8e3","name":"hello.uz","description":"","isPrimary":false,"userMaxCount":0,"outgoingMessageLimit":{"isActive":false,"limit":{"value":0,"units":"Bytes"}},"keepForRecovery":{"isEnabled":false,"days":0},"aliasList":[],"forwardingOptions":{"isEnabled":false,"host":"","port":0,"how":"Online","preventLoop":false},"kerberosRealm":"","winNtName":"","pamRealm":"","ipAddressBind":{"enabled":false,"value":"0.0.0.0"},"renameInfo":{"isRenamed":false,"oldName":"","newName":""},"isDistributed":false},{"id":"keriodb://domain/a53c0d7e-427f-4a7b-a63f-3d947fc89454","name":"ivan.com","description":"","isPrimary":false,"userMaxCount":0,"outgoingMessageLimit":{"isActive":false,"limit":{"value":0,"units":"Bytes"}},"keepForRecovery":{"isEnabled":false,"days":0},"aliasList":[],"forwardingOptions":{"isEnabled":false,"host":"","port":0,"how":"Online","preventLoop":false},"kerberosRealm":"","winNtName":"","pamRealm":"","ipAddressBind":{"enabled":false,"value":"0.0.0.0"},"renameInfo":{"isRenamed":false,"oldName":"","newName":""},"isDistributed":false},{"id":"keriodb://domain/44ecc1fb-fba3-4a75-b4b9-9f2528e50995","name":"kidat.de","description":"","isPrimary":false,"userMaxCount":0,"outgoingMessageLimit":{"isActive":false,"limit":{"value":0,"units":"Bytes"}},"keepForRecovery":{"isEnabled":false,"days":0},"aliasList":[],"forwardingOptions":{"isEnabled":false,"host":"","port":0,"how":"Online","preventLoop":false},"kerberosRealm":"","winNtName":"","pamRealm":"","ipAddressBind":{"enabled":false,"value":"0.0.0.0"},"renameInfo":{"isRenamed":false,"oldName":"","newName":""},"isDistributed":false},{"id":"keriodb://domain/ef0698e4-8661-47e0-83df-73f729e4beab","name":"mm","description":"","isPrimary":false,"userMaxCount":0,"outgoingMessageLimit":{"isActive":false,"limit":{"value":0,"units":"Bytes"}},"keepForRecovery":{"isEnabled":false,"days":0},"aliasList":[],"forwardingOptions":{"isEnabled":false,"host":"","port":0,"how":"Online","preventLoop":false},"kerberosRealm":"","winNtName":"","pamRealm":"","ipAddressBind":{"enabled":false,"value":"0.0.0.0"},"renameInfo":{"isRenamed":false,"oldName":"","newName":""},"isDistributed":false},{"id":"keriodb://domain/2557ab49-819e-4227-a212-6ddb524f146f","name":"mykerio.co.uk","description":"","isPrimary":false,"userMaxCount":0,"outgoingMessageLimit":{"isActive":false,"limit":{"value":0,"units":"Bytes"}},"keepForRecovery":{"isEnabled":false,"days":0},"aliasList":[],"forwardingOptions":{"isEnabled":false,"host":"","port":0,"how":"Online","preventLoop":false},"kerberosRealm":"","winNtName":"","pamRealm":"","ipAddressBind":{"enabled":false,"value":"0.0.0.0"},"renameInfo":{"isRenamed":false,"oldName":"","newName":""},"isDistributed":false},{"id":"keriodb://domain/1935afd9-bdf1-4820-8135-a098c7d323e6","name":"prueba.es","description":"","isPrimary":false,"userMaxCount":0,"outgoingMessageLimit":{"isActive":false,"limit":{"value":0,"units":"Bytes"}},"keepForRecovery":{"isEnabled":false,"days":0},"aliasList":[],"forwardingOptions":{"isEnabled":false,"host":"","port":0,"how":"Online","preventLoop":false},"kerberosRealm":"","winNtName":"","pamRealm":"","ipAddressBind":{"enabled":false,"value":"0.0.0.0"},"renameInfo":{"isRenamed":false,"oldName":"","newName":""},"isDistributed":false},{"id":"keriodb://domain/d85f3510-7809-47d6-9ec3-94e8767756a4","name":"sadss","description":"","isPrimary":false,"userMaxCount":0,"outgoingMessageLimit":{"isActive":false,"limit":{"value":0,"units":"Bytes"}},"keepForRecovery":{"isEnabled":false,"days":0},"aliasList":[],"forwardingOptions":{"isEnabled":false,"host":"","port":0,"how":"Online","preventLoop":false},"kerberosRealm":"","winNtName":"","pamRealm":"","ipAddressBind":{"enabled":false,"value":"0.0.0.0"},"renameInfo":{"isRenamed":false,"oldName":"","newName":""},"isDistributed":false},{"id":"keriodb://domain/ba9c64c9-96c7-4c9b-8005-d731688ef1cc","name":"sdsd","description":"","isPrimary":false,"userMaxCount":0,"outgoingMessageLimit":{"isActive":false,"limit":{"value":0,"units":"Bytes"}},"keepForRecovery":{"isEnabled":false,"days":0},"aliasList":[],"forwardingOptions":{"isEnabled":false,"host":"","port":0,"how":"Online","preventLoop":false},"kerberosRealm":"","winNtName":"","pamRealm":"","ipAddressBind":{"enabled":false,"value":"0.0.0.0"},"renameInfo":{"isRenamed":false,"oldName":"","newName":""},"isDistributed":false},{"id":"keriodb://domain/75fcc0b7-fc1d-434c-a1a4-e1ab2385a5b9","name":"test","description":"","isPrimary":false,"userMaxCount":0,"outgoingMessageLimit":{"isActive":false,"limit":{"value":0,"units":"Bytes"}},"keepForRecovery":{"isEnabled":false,"days":0},"aliasList":[],"forwardingOptions":{"isEnabled":false,"host":"","port":0,"how":"Online","preventLoop":false},"kerberosRealm":"","winNtName":"","pamRealm":"","ipAddressBind":{"enabled":false,"value":"0.0.0.0"},"renameInfo":{"isRenamed":false,"oldName":"","newName":""},"isDistributed":false},{"id":"keriodb://domain/5a99acb8-bcf2-49b1-9255-502ed8691937","name":"test1","description":"","isPrimary":false,"userMaxCount":0,"outgoingMessageLimit":{"isActive":false,"limit":{"value":0,"units":"Bytes"}},"keepForRecovery":{"isEnabled":false,"days":0},"aliasList":[],"forwardingOptions":{"isEnabled":false,"host":"","port":0,"how":"Online","preventLoop":false},"kerberosRealm":"","winNtName":"","pamRealm":"","ipAddressBind":{"enabled":false,"value":"0.0.0.0"},"renameInfo":{"isRenamed":false,"oldName":"","newName":""},"isDistributed":false},{"id":"keriodb://domain/52c5bef2-7595-484c-8c3c-183b9a533c8c","name":"testtset.com","description":"","isPrimary":false,"userMaxCount":0,"outgoingMessageLimit":{"isActive":false,"limit":{"value":0,"units":"Bytes"}},"keepForRecovery":{"isEnabled":false,"days":0},"aliasList":[],"forwardingOptions":{"isEnabled":false,"host":"","port":0,"how":"Online","preventLoop":false},"kerberosRealm":"","winNtName":"","pamRealm":"","ipAddressBind":{"enabled":false,"value":"0.0.0.0"},"renameInfo":{"isRenamed":false,"oldName":"","newName":""},"isDistributed":false},{"id":"keriodb://domain/011e9e1a-bc49-4625-895d-d7726bdb292a","name":"tetu","description":"","isPrimary":false,"userMaxCount":0,"outgoingMessageLimit":{"isActive":false,"limit":{"value":0,"units":"Bytes"}},"keepForRecovery":{"isEnabled":false,"days":0},"aliasList":[],"forwardingOptions":{"isEnabled":false,"host":"","port":0,"how":"Online","preventLoop":false},"kerberosRealm":"","winNtName":"","pamRealm":"","ipAddressBind":{"enabled":false,"value":"0.0.0.0"},"renameInfo":{"isRenamed":false,"oldName":"","newName":""},"isDistributed":false},{"id":"keriodb://domain/4d68d9e6-db5c-47db-8bfc-6e6b0117253b","name":"trydemo","description":"","isPrimary":false,"userMaxCount":0,"outgoingMessageLimit":{"isActive":false,"limit":{"value":0,"units":"Bytes"}},"keepForRecovery":{"isEnabled":false,"days":0},"aliasList":[],"forwardingOptions":{"isEnabled":false,"host":"","port":0,"how":"Online","preventLoop":false},"kerberosRealm":"","winNtName":"","pamRealm":"","ipAddressBind":{"enabled":false,"value":"0.0.0.0"},"renameInfo":{"isRenamed":false,"oldName":"","newName":""},"isDistributed":false},{"id":"keriodb://domain/22a7aa5c-eab7-491f-a9a5-bbb603744eee","name":"udoniko","description":"","isPrimary":false,"userMaxCount":0,"outgoingMessageLimit":{"isActive":false,"limit":{"value":0,"units":"Bytes"}},"keepForRecovery":{"isEnabled":false,"days":0},"aliasList":[],"forwardingOptions":{"isEnabled":false,"host":"","port":0,"how":"Online","preventLoop":false},"kerberosRealm":"","winNtName":"","pamRealm":"","ipAddressBind":{"enabled":false,"value":"0.0.0.0"},"renameInfo":{"isRenamed":false,"oldName":"","newName":""},"isDistributed":false},{"id":"keriodb://domain/5a38e5c0-746d-4b95-a371-c11c54754d55","name":"xxxbertxxx","description":"","isPrimary":false,"userMaxCount":0,"outgoingMessageLimit":{"isActive":false,"limit":{"value":0,"units":"Bytes"}},"keepForRecovery":{"isEnabled":false,"days":0},"aliasList":[],"forwardingOptions":{"isEnabled":false,"host":"","port":0,"how":"Online","preventLoop":false},"kerberosRealm":"","winNtName":"","pamRealm":"","ipAddressBind":{"enabled":false,"value":"0.0.0.0"},"renameInfo":{"isRenamed":false,"oldName":"","newName":""},"isDistributed":false},{"id":"keriodb://domain/5c72404d-1cc3-47ac-8833-33fbed1edad7","name":"zxczxccz","description":"","isPrimary":false,"userMaxCount":0,"outgoingMessageLimit":{"isActive":false,"limit":{"value":0,"units":"Bytes"}},"keepForRecovery":{"isEnabled":false,"days":0},"aliasList":[],"forwardingOptions":{"isEnabled":false,"host":"","port":0,"how":"Online","preventLoop":false},"kerberosRealm":"","winNtName":"","pamRealm":"","ipAddressBind":{"enabled":false,"value":"0.0.0.0"},"renameInfo":{"isRenamed":false,"oldName":"","newName":""},"isDistributed":false}],"totalItems":21}}

4. Logout

At the end, it is a good practice to logout and close connection to the server. You are done.

Request

POST /admin/api/jsonrpc/ HTTP/1.1
Accept: application/json-rpc
Content-Type: application/json-rpc; charset=UTF-8
User-Agent: Kerio APIs Client Library for PHP/1.3
Host: mail.company.tld:4040
Content-Length: 127
Connection: close
Cookie:  SESSION_CONNECT_WEBADMIN=ff313031fce1015030d208542172d0bab257633bb1ff94f6fafb17be53f1415f;
X-Token: 661415af99698a00d9e2a3335350d0c27e14c032fe34c7c52d853e13908c6791

{"jsonrpc":"2.0","id":4,"token":"661415af99698a00d9e2a3335350d0c27e14c032fe34c7c52d853e13908c6791","method":"Session.logout"}

Response

HTTP/1.1 200 OK
Connection: Close
Content-Type: application/json-rpc; charset=utf-8
Date: Thu, 28 Aug 2014 06:46:36 GMT
Server: Kerio Connect 8.3.1
X-Frame-Options: SAMEORIGIN
X-UA-Compatible: IE=edge

{"jsonrpc":"2.0","id":4,"result":{"redirectUrl":"https://mail.company.tld:4040/admin/login"}}