How to start with IceWarp API

This article is designed for developers and administrators, who want to control their IceWarp server using 3rd party application, typically CRM. Every developer who is starting with API can spend several hours by reading the documentation avaiable via icewarp.com/product/api/, or he can go through this article and create first API call within minutes. This article is tutorial with examples and hints how to start effectively. It does not substitute full documentation.

TL;DR. IceWarp WebAdmin is using very same API. Just use the WebAdmin to configure anything you want, catch the requests using browser console, re-use in your product.

Longer explanation and step by step guide follows.

Expected knowledge

To understanding the article, elementary knowledge of certain technologies is expected:

• API, SOAP and HTTPS request sending problematics.
• Postman, CURL or similar tools.
• XML and parsing.

Only things you really need to know or have

• Download and install Postman to your PC. Experienced administrators/developers can use curl write the examples directly to the code of their own software.
• Install and configure IceWarp server or easily start free IceWarp Cloud trial instance via icewarp.com
• Sign in to WebAdmin as a administrator.
• Use the Chrome browser and it's build in developer console (ctrl+shift+I).

Part 1 - learn to catch the existing requests

You do not have to create elementary requests from the scratch. IceWarp WebAdmin is using very same API for configuring the IceWarp server.

1. Login to the IceWarp WebAdmin, e.g. using https://yourdomain.onice.io/admin.
2. Click plus button (left top) and choose New domain.
3. Fill in the name of the domain, e.g. newdomain.local.
4. Do not save it.
5. Use Ctrl+Shift+I to open the DevTools console. Make sure you are on a network tab.
6. Optional - if not empty, use the clear button to clear the list. Also make sure recording button is enabled (red).
7. Return to the WebAdmin and click Save to confirm new domain creation.
8. On the previously opened network tab of the developer console, new communication is recorded.
9. Optional - use recording button to stop the communication (change the button colour to grey).
10. In the list of the communication, search for icewarpapi with the CreateDomain text in the payload tab. This is the call which you can re-use.
11. On the Response tab, you can find the answer to your request. This will be the response you might want to parse in your product later (where applicable).

HTTP request described above might look like:

And related response:

Part 2 - copy the http request to the Postman

1. Open Postman.
2. Create new http request using
   1. Post method.
   2. URL https://yourdomain.onice.io/icewarpapi/
   3. Switch to Body -> raw  and copy the xml call.
   4. Copy the payload created in a previous Part to the body of a request in a postman.
   5. Do not forget to change the domain name or delete the domain previously created.
3. Hit the Send button.
4. Check the response window (in the default view positioned below).

Steps described above might result in:

Note: SID shown in the picture is stored in {{sid}} variable and not directly. It is not necessary for this tutorial, but feel free to read more about Postman variables.

Part 3 - self-study - create new user

By repeating approach described in the part 1 and 2, catch the call for creating user and then re-use it with the Postman. Try to change name and surname, or do not use  it at all during your experiments, to understand how to handle call with variable number of parameters.

Part 4 - delete the domain and understand variability of responses

By approach similar to the Part 2, call the domain creation and deletion using Postman. To speed up the process, requests are below. Copy them and change the SID to the one you have in your webbrowser console. Changing the domain name is optional.

Domain creation

<iq sid="{{sid}}" type="set" format="application/xml">
    <query xmlns="admin:iq:rpc">
        <commandname>CreateDomain</commandname>
        <commandparams>
            <domainstr>deleteme.com</domainstr>
        </commandparams>
    </query>
</iq>

Domain deletion

<iq sid="{{sid}}" uid="123" type="set" format="application/xml">
    <query xmlns="admin:iq:rpc">
        <commandname>deletedomain</commandname>
        <commandparams>
            <domainstr>deleteme.com</domainstr>
        </commandparams>
    </query>
</iq>

Now check the response. It should look like this:

Hit the send button in the Postman again to resend delete request. Response is changed:

Please keep in mind, that the API call response may vary based not only on the variables sent, but also on the current situation and cofiguration of the IceWarp server. Take it into account while implementing the calls into your product.

Part 5 - How to authenticate and get SID

Every request discussed so far did not use username and a password. Despite the fact this article expects most of you understand what is SID, brief summary for the rest of the readers follows.  If you do not know what SID is, understand it as identifier of the session or it's hash/token, which has already been authorized. It's validity is driven by the webserver which authorized communication and expires after period of the time which is again defined by (=configured on) this server.

There is one specific call you will probably use in your own product as a first request and it gives you the SID as a response to API call. Authenticate request:

<iq uid="1" format="text/xml">
    <query xmlns="admin:iq:rpc" >
        <commandname>authenticate</commandname>
        <commandparams>
            <email>user@yourdomain.onice.io</email>
            <password>ComplicatedPasswordads5f456df46asf46a+</password>
            <digest></digest>
            <authtype>0</authtype>
            <persistentlogin>0</persistentlogin>
        </commandparams>
    </query>
</iq>

Part 6 - final thoughts

• Do not be afraid and experiment.
• Try to implement the HTTP calls into bash using CURL.
• Use the WebAdmin to list different properties of a users/domains and check the calls and their responses.

Part 7 - Example of bash script

Script zipped and attached to this article loads the list of the users from the specified domain on the specified server and using cycle, it returns last login date of every user. All files necessary to run are in an attached .zip file. Do not forget to fill the config.txt with necessary information - IceWarp server address, SID and the domain.