Hi all!
We are bringing out HTTP API for doveadm-server in master HEAD. This feature is
experimental, and can be expected to have bugs in it and might not always work.
If you feel like trying it out though, you can enable it in your configuration
file:
doveadm_api_key = some-string
service doveadm {
inet_listener http {
port = 8080
}
}
To use the API, you can go to http://host:8080/doveadm. GET request will print
out possible commands, along with their parameters. If you have set API KEY, you
need to include it in the request as X-API-Key header.
This API has been designed to resemble JMAP API since we are planning to
implement it in future version.
The rule of thumb is that all the commands work as they would on cli, so the
parameters are more or less the same. There are few exceptions, like
'field'
parameter in some mail/mailbox commands.
Commands are executed by POSTin JSON to /doveadm. The JSON format is
[
["command",{"parameter":"value"},"opaque
identifier"],
["command",{"parameter":"value"},"opaque
identifier"],
["command",{"parameter":"value"},"opaque
identifier"],
...
]
Be warned though that even if it supports multiple commands, some commands still
use i_fatal to terminate the server if they are unhappy. This will mean you will
lose the whole result set, and get no output, so at this point it is safest
option to run only one command at a time.
If you run into problems or discover issues, please report them in the usual
manner to us.
Kind regards,
Aki Tuomi
Dovecot Oy
On 2016-02-20 17:09, aki.tuomi at dovecot.fi wrote:> To use the API, you can go to http://host:8080/doveadm.The documentation says http://host:8080/doveadm/v1 which is it?> GET request will print > out possible commands, along with their parameters. If you have set API > KEY, you > need to include it in the request as X-API-Key header.The documentation says X-Doveadm-API, which is it? A simple 1-line curl-example in the docs would do wonders :) http://wiki2.dovecot.org/Design/DoveadmProtocol/HTTP Thanks. // Tom
> On April 4, 2016 at 5:18 PM Tom Sommer <mail at tomsommer.dk> wrote: > > > > On 2016-02-20 17:09, aki.tuomi at dovecot.fi wrote: > > > To use the API, you can go to http://host:8080/doveadm. > > The documentation says http://host:8080/doveadm/v1 which is it? > > > GET request will print > > out possible commands, along with their parameters. If you have set API > > KEY, you > > need to include it in the request as X-API-Key header. > > The documentation says X-Doveadm-API, which is it? > > A simple 1-line curl-example in the docs would do wonders :) > > http://wiki2.dovecot.org/Design/DoveadmProtocol/HTTP > > Thanks. > > // TomHi! Yes, you're right. I'll add this line to the docs as well, and also I discovered a bug in the code. It will be fixed in next release. The response indicates X-Dovecot-API, but the code uses X-Doveadm-API, this has been fixed to X-Dovecot-API. For now, if you want to use BASIC authentication, you set doveadm_password to something and use curl -H "Authorization: Basic <base64 username:password>" http://server:8080/ to get acceptable routes curl -H "Authorization: Basic <base64 username:password>" http://server:8080/doveadm/v1 to get acceptable commands and their parameters curl -H "Authorization: Basic <base64 username:password>" http://server:8080/doveadm/v1 an example command would be curl -H "Content-Type: application/json" -H "Authorization: Basic <base64 username:password>" -d '[["fetch",{"user":"username","field":["uid"],"query":["mailbox","INBOX"]},"c01"]]' http://server:8080/doveadm/v1 this should hopefully return something sensible, such as [["doveadmResponse",[{"uid":"1"}],"c01"]] Since the API is still a little beta, it will not return anything in case doveadm does not like the arguments (that is, calls i_fatal). Also, success is often indicated with 200 OK along with [["doveadmResponse",[],"c01"]]. We are going to improve the API in future release with v2, v1 is basically very analogous to using doveadm cli. Aki
> On April 5, 2016 at 9:27 AM Tom Sommer <mail at tomsommer.dk> wrote: > > > On 2016-04-04 20:22, aki.tuomi at dovecot.fi wrote: > > > Since the API is still a little beta, it will not return anything in > > case > > doveadm does not like the arguments (that is, calls i_fatal). Also, > > success is > > often indicated with 200 OK along with [["doveadmResponse",[],"c01"]]. > > I don't see the "doveadm proxy kick" command in the list?Not all commands are included, unfortunately. Also, the list only shows commands that are available with doveadm as per configuration. Aki
On 2016-04-05 08:44, aki.tuomi at dovecot.fi wrote:>> On April 5, 2016 at 9:27 AM Tom Sommer <mail at tomsommer.dk> wrote: >> >> >> On 2016-04-04 20:22, aki.tuomi at dovecot.fi wrote: >> >> > Since the API is still a little beta, it will not return anything in >> > case >> > doveadm does not like the arguments (that is, calls i_fatal). Also, >> > success is >> > often indicated with 200 OK along with [["doveadmResponse",[],"c01"]]. >> >> I don't see the "doveadm proxy kick" command in the list? > > Not all commands are included, unfortunately. Also, the list only > shows commands that are available with doveadm as per configuration.Hrmm, is it possible to add a non-http inet_listener to doveadm? And feed it commands directly? I really need a remote proxy kick for my director.