Doveadm HTTP API
================

Doveadm HTTP API is available since v2.2.22. It is considered *experimental* in
v2.2.22. Can be considered as stable since 2.2.23. It lets you perform doveadm
commands over HTTP transport.

Configuration
-------------

To enable HTTP API, add following to your config file:

---%<-------------------------------------------------------------------------
service doveadm {
   inet_listener http {
      port = 8080
      #ssl = yes # uncomment to enable https
   }
}
---%<-------------------------------------------------------------------------

To enable SSL make sure 'ssl=yes' or 'ssl=required' in global settings, and set
'ssl=yes' in the listener.

You can use unix listener too, and define host to listen on. You also need to
either define 'doveadm_password', or 'doveadm_api_key'. With
'doveadm_password', the username is doveadm. This is going to change in future
release. With API Key you are expected to send

---%<-------------------------------------------------------------------------
Authorization: X-Dovecot-API Base64(apikey)
---%<-------------------------------------------------------------------------

header to access the API. (In v2.2.22-2.2.23, this key was incorrectly
"X-Doveadm-API".)

Usage
-----

You can see valid commands and their parameters by accessing
'http://host:port/doveadm/v1'.

To send command(s), you can send following with 'Content-Type:
application/json'

---%<-------------------------------------------------------------------------
[
  ["command", {"parameter":"value"}, "optional identifer"]
]
---%<-------------------------------------------------------------------------

In following examples, you can either use Basic or X-Dovecot-API authorization.
X-Dovecot-API usage:

---%<-------------------------------------------------------------------------
curl -H "Authorization: X-Dovecot-API <base64 dovecot_api_key>"
---%<-------------------------------------------------------------------------

Basic authorization uses "doveadm" as the username, and doveadm_password
setting as the password:

---%<-------------------------------------------------------------------------
curl -H "Authorization: Basic <base64 doveadm:doveadm_password>"
---%<-------------------------------------------------------------------------

To get acceptable routes

---%<-------------------------------------------------------------------------
curl -H "Authorization: Basic <base64 doveadm:doveadm_password>"
http://server:8080/
---%<-------------------------------------------------------------------------

To get acceptable commands and their parameters

---%<-------------------------------------------------------------------------
curl -H "Authorization: Basic <base64 doveadm:doveadm_password>"
http://server:8080/doveadm/v1
---%<-------------------------------------------------------------------------

an example command would be

---%<-------------------------------------------------------------------------
curl -H "Content-Type: application/json" -H "Authorization: Basic <base64
doveadm:doveadm_password>" -d
'[["fetch",{"user":"username","field":["uid"],"query":["mailbox","INBOX"]},"c01"]]'
http://server:8080/doveadm/v1
---%<-------------------------------------------------------------------------

You can have multiple commands in the array, but for now it is safest *not* to
do so, as some commands may kill the server in certain error conditions and
leaving you without any response.

Responses are in same format, command is replaced with either "error" or
"doveadmResponse" and parameters with array of response variables. In case of
*successful* command which has *no* output, response is going to be [].

Errors are indicated with "error" and type, exit-code in response part.

Logging
-------

The logs will indicated execute command(s) and also Apache access.log format
strings on requests. In case of fatal errors, the access.log string might be
missing.

Example clients
---------------

 * A PoC API client/library written in Python is available at
   https://github.com/hnsk/doveadm-http-cli
 * See also internal doveadm protocol clients in <Design.DoveadmProtocol.txt>

(This file was created from the wiki on 2019-06-19 12:42)