Template:DoveadmHTTPapi

doveadm http api

configuration

To be able to use doveadm http api it’s mandatory to configure either password for doveadm or a api key.

To configure password for doveadm service in /etc/dovecot/dovecot.conf:

doveadm_password = hellodoveadm

Or if preferred to use separate key for doveadm http api then it can be enabled by defining key in config:

doveadm_api_key = key

And to enable the doveadm http listener:

 service doveadm {
  unix_listener doveadm-server {
    user = vmail
  }
  inet_listener {
   port = 2425
  }
  inet_listener http {
    port = 8080
    #ssl = yes # uncomment to enable https
  }
} 
 

usage

connecting to endpoint can then be done by using standard http protocol and authentication headers. To get list the commands supported by the endpoint, the following example commands can be used:

X-Dovecot-API auth usage:

curl -H "Authorization: X-Dovecot-API <base64 dovecot_api_key>" http://host:port/doveadm/v1

Basic auth usage:

curl -H "Authorization: Basic <base64 doveadm:doveadm_password>" http://host:port/doveadm/v1

or by letting curl to form the base64 encoded authentication basig authentication header:

curl –u doveadm:password http://host:port/doveadm/v1

command usage

All commands sent to the API needs to be posted in json format using “Content-Type: application/json” in headers for the request type and the json content as payload in format:

[
    [
        "command1",
        {
            "parameter1": "value",
            "parameter2": "value",
            "parameter3": "value"
        },
        "identifier"
    ]
]
 

Multiple commands can be submitted in one json payload:

[
    [
        "command1",
        {
            "parameter1": "value",
            "parameter2": "value"
        },
        "identifier1"
    ],
    [
        "command2",
        {
            "parameter1": "value",
            "parameter2": "value"
        },
        "identifier2"
    ]
]
 

For now it is safest not to send multiple commands in one json payload, as some commands may kill the server in certain error conditions and leaving you without any response. Also it is not guaranteed that the commands will be processed in order.

All commands are case sensitive.

example usage

In the example we ask dovecot to reload configuration:

son payload:

[
    [
        "reload",
        {},
        "a2"
    ]
]

 

submitting the command with curl:

1. curl -v -u doveadm:hellodoveadm -X POST http://localhost:8080/doveadm/v1 -H "Content-Type: application/json" -d '[["reload",{},"a2"]]'

command line equivalent

doveadm reload

successful response

[
    [
        "doveadmResponse",
        [],
        "a2"
    ]
]
 

failure response

[
    [
        "error",
        {
            "exitCode": 68,
            "type": "exitCode"
        },
        "a2"
    ]
 

failure codes

2	Success but mailbox changed during operation
64	Invalid parameters
65	Data error
67	User does not exist
68	User does not have session
73	User out of quota
75	Temporary error
77	No permission
78	valid configuration