Open-Xchange - User contributions [en]

Template:DoveadmHTTPapi

2017-03-15T12:42:39Z

Oskarikentta: /* doveadm altmove */

== Table of Contents ==
__TOC__

== 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:

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

=== 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:

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

Basic auth usage:
<nowiki>
curl -H "Authorization: Basic <base64 doveadm:doveadm_password>"
http://host:port/doveadm/v1
</nowiki>
or by letting curl to form the base64 encoded authentication basig authentication header:

<nowiki>
curl –u doveadm:password http://host:port/doveadm/v1
</nowiki>

=== 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:

<nowiki>

[
[
"command1",
{
"parameter1": "value",
"parameter2": "value",
"parameter3": "value"
},
"identifier"
]
]
</nowiki>
Multiple commands can be submitted in one json payload:
<nowiki>
[
[
"command1",
{
"parameter1": "value",
"parameter2": "value"
},
"identifier1"
],
[
"command2",
{
"parameter1": "value",
"parameter2": "value"
},
"identifier2"
]
]
</nowiki>

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:

<nowiki>

son payload:

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

</nowiki>

submitting the command with curl:

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

command line equivalent

doveadm reload

=== successful response ===

<nowiki>

[
[
"doveadmResponse",
[],
"a2"
]
]
</nowiki>

=== failure response ===

<nowiki>

[
[
"error",
{
"exitCode": 68,
"type": "exitCode"
},
"a2"
]
</nowiki>

=== failure codes ===

{| class="wikitable"
|-
|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
|}

== Supported commands ==

== doveadm service ==
=== doveadm service stop ===

stop one or more dovecot services on target host

<nowiki>
{
"command": "serviceStop",
"parameters": [
{
"name": "service",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|service
|string array
|Name of service to stop
|[“imap”,”imap-hibernate”]
|}

example:

<nowiki>
[
[
"serviceStop",
{
"service": [
"imap",
"imap-hibernate"
]
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["serviceStop",{"service":["imap","imap-hibernate"]},"aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm service stop imap imap-hibernate
</nowiki>

=== doveadm stop ===

stop dovecot on the target host
<nowiki>

{
"command": "stop",
"parameters": []
}

no parameters
</nowiki>
example:
<nowiki>
[
[
"stop",
{},
"a1"
]
]

# curl -u doveadm:hellodoveadm -X POST http://localhost:8080/doveadm/v1 -H "Content-Type: application/json" -d '[["stop",{},"a1"]]'

CLI: doveadm stop
</nowiki>

=== doveadm reload ===

reload dovecot configuration

<nowiki>
{
"command": "reload",
"parameters": []
}
</nowiki>

example:

<nowiki>
[
[
"reload",
{},
"a2"
]
]

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

CLI: doveadm reload
</nowiki>

== doveadm stats ==
=== doveadm stats dump ===

dump collected dovecot statistics

<nowiki>
{
"command": "statsDump",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "type",
"type": "string"
},
{
"name": "filter",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|+parameters
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|type
|String
|Type of stats to dump
|global
|-
|filter
|String
|Dump filter
|last_update 1483101542
|}

Example:

<nowiki>
[
[
"statsDump",
{
"type": "global"
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["statsDump",{"type":"global"},"aa"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"auth_cache_hits": "0",
"auth_cache_misses": "0",
"auth_db_tempfails": "0",
"auth_failures": "0",
"auth_master_successes": "0",
"auth_successes": "0",
"clock_time": "0.0",
"disk_input": "0",
"disk_output": "0",
"fscache_read": "0",
"fscache_stat": "0",
"fscache_write": "0",
"idx_del": "0",
"idx_iter": "0",
"idx_read": "0",
"idx_read_usecs": "0",
"idx_wbytes": "0",
"idx_write": "0",
"idx_write_usecs": "0",
"invol_cs": "0",
"last_update": "0.000000",
"mail_cache_hits": "0",
"mail_lookup_attr": "0",
"mail_lookup_path": "0",
"mail_read_bytes": "0",
"mail_read_count": "0",
"maj_faults": "0",
"min_faults": "0",
"num_cmds": "0",
"num_connected_sessions": "0",
"num_logins": "0",
"obox_copy": "0",
"obox_del": "0",
"obox_iter": "0",
"obox_read": "0",
"obox_read_usecs": "0",
"obox_stat": "0",
"obox_wbytes": "0",
"obox_write": "0",
"obox_write_usecs": "0",
"read_bytes": "0",
"read_count": "0",
"reset_timestamp": "1483104199",
"sys_cpu": "0.0",
"user_cpu": "0.0",
"vol_cs": "0",
"write_bytes": "0",
"write_count": "0"
}
],
"aa"
]
]

CLI: doveadm stats dump global
</nowiki>

=== doveadm stats reset ===
reset dovecot statistics counters
<nowiki>

{
"command": "statsReset",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|}

example:

<nowiki>
[
[
"statsReset",
{},
"aa"
]
]

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

CLI: doveadm stats reset
</nowiki>

== doveadm penalty ==

<nowiki>
show current penalties

{
"command": "penalty",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "netmask",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|string
|Path to doveadm socket
|/var/run/dovecot-server
|-
|netmask
|string
|To reduce/filter the output supply an IP address or a network range in CIDR notation (ip/mask)
|10.0.0.0/24
|}

example:

<nowiki>
[
[
"penalty",
{},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["penalty",{},"aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm penalty
</nowiki>

== doveadm kick ==

Kick user from dovecot. Applicable to session in dovecot backend only

<nowiki>
{
"command": "kick",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "force",
"type": "boolean"
},
{
"name": "mask",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|force
|Boolean
|Do a forced kick?
|0
|-
|mask
|String
|Uid mask
|testuser001
|}

example:

<nowiki>
[
[
"kick",
{
"force": 0,
"mask": "testuser001"
},
"aa"
]
]

# curl -v -u doveadm:hellodoveadm –H “Content-Type: application/json" -d '[["kick", {"mask":"testuser001"}, "aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm kick testuser001
</nowiki>

response for succesfull kick:

<nowiki>
[
[
"doveadmResponse",
[
{
"result": "testuser001"
}
],
"aa"
]
]
</nowiki>

response in case kick failed:

<nowiki>
[
[
"error",
{
"exitCode": 68,
"type": "exitCode"
},
"aa"
]
]
</nowiki>

== doveadm who ==

<nowiki>
list active dovecot sessions

{
"command": "who",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "separateConnections",
"type": "boolean"
},
{
"name": "mask",
"type": "array"
}
]
}
</nowiki>

parameters

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|string
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|separateConnections
|Boolean
|Show each user connection in separate entries
|0
|-
|mask
|string array
|Uid mask
|testuser001
|}

Example:

<nowiki>
[
[
"who",
{
"mask": "",
"separateConnections": 0,
"socketPath": ""
},
"aa"
]
]

# curl -v -u doveadm:hellodoveadm -X POST http://localhost:ype: application/json" -d '[["who", {}, "aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm who
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"connections": "1",
"ips": "(127.0.0.1)",
"pids": "(4999)",
"service": "imap",
"username": "testuser001"
}
],
"aa"
]
]
</nowiki>

== doveadm director ==
=== doveadm director status ===

Show backend statuses on directors. Available only in directors

<nowiki>
[
{
"command": "directorStatus",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "tag",
"type": "string"
}
]
}
]
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|String
|Show director status for Tagged hosts only
|NewBackend
|}

example:

<nowiki>
[
[
"directorStatus",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorStatus",{},"bb"]]' http://localhost:8080/doveadm/v1

</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"mail server ip": "10.0.0.234",
"state": "up",
"state-changed": "2016-12-15 08:31:37",
"tag": "",
"users": "1",
"vhosts": "100"
},
{
"mail server ip": "10.0.0.235",
"state": "up",
"state-changed": "2016-12-15 08:31:04",
"tag": "",
"users": "0",
"vhosts": "100"
}
],
"bb"
]
]

CLI: doveadm director status
</nowiki>

=== doveadm director map ===

list current user → host mappings. Applicable to director only

<nowiki>

"command": "directorMap",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "usersFile",
"type": "string"
},
{
"name": "hashMap",
"type": "boolean"
},
{
"name": "userMap",
"type": "boolean"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

parameters

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|usersFile
|String
|provide Path to users list. One username per line
|/etc/dovecot/userlist.txt
|-
|hashMap
|Boolean
|Output users as hashmap
|True
|-
|userMap
|Boolean
|Output users as userlist
|True
|-
|host
|String
|Show only mappings to given host
|10.0.0.234
|}

example:

<nowiki>
[
[
"directorMap",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorMap",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"expire time": "2016-12-30 14:52:56",
"hash": "3853430566",
"mail server ip": "10.0.0.235",
"user": "samik"
}
],
"bb"
]
]

CLI: doveadm director map
</nowiki>

=== doveadm director add ===

add backend to director ring

<nowiki>
{
"command": "directorAdd",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "tag",
"type": "string"
},
{
"name": "host",
"type": "string"
},
{
"name": "vhostCount",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|tag
|String
|apply tag to backend
|/etc/dovecot/userlist.txt
|-
|host
|String
|backend ip to add
|10.0.0.234
|-
|vhostCount
|String
|vhost count to add
|100
|}

Example:

<nowiki>
[
[
"directorAdd",
{
"host": "10.0.234"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorAdd",{"host":"10.0.234"},"bb"]]' http://localhost:8080/doveadm/v1

CLI: doveadm director add 10.0.0.234
</nowiki>

=== doveadm director update ===

<nowiki>
{
"command": "directorUpdate",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
},
{
"name": "vhostCount",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|string
|Show director status for tagged hosts only
|NewBackend
|}

=== doveadm director up ===

<nowiki>
{
"command": "directorUp",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|string
|Show director status for tagged hosts only
|NewBackend
|}

=== doveadm director down ===

<nowiki>
{
"command": "directorDown",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|string
|Show director status for tagged hosts only
|NewBackend
|}

=== doveadm director remove ===

remove backend from director ring

<nowiki>
{
"command": "directorRemove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|host
|String
|backend to remove
|10.0.0.134
|}

example:

<nowiki>
[
[
"directorRemove",
{
"host": "10.0.0.234"
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRemove",{"host":"10.0.0.234"},"aa"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"aa"
]
]

CLI: doveadm director remove 10.0.0.234
</nowiki>

=== doveadm director move ===

move user mapping from backend to another or create director mapping for an user
<nowiki>
{
"command": "directorMove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|user
|String
|User uid to move
|testuser001
|-
|host
|string
|Target backend ip as listed in doveadm doveadm director status
|10.0.0.234
|}

example:

<nowiki>
[
[
"directorMove",
{
"host": "10.0.234",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorMove",{"user":"samik","host":"10.0.234"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director move samik 10.0.0.234
</nowiki>

== doveadm director kick ==

<nowiki>
{
"command": "directorKick",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|user
|String
|uid of user to kick
|samik
|}

example:

<nowiki>
[
[
"directorKick",
{
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorKick",{"user":"samik"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director kick samik
</nowiki>

=== doveadm director flush ===

flush connection mappings to one backend at director level. All users mapped to given host will be flushed from the hashmap table and will be redistributed to backends.

Parameters:

<nowiki>
{
"command": "directorFlush",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "forceFlush",
"type": "boolean"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|forceFlush
|Boolean
|Flag to make flush forced
|True
|-
|host
|String
|Backend ip address from doveadm director status list
|10.0.0.234
|}

example:

<nowiki>
[
[
"directorFlush",
{
"host": "10.0.0.234"
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorFlush",{"host":"10.0.0.234"},"aa"]]' http://localhost:8080/doveadm/v1

</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"aa"
]
]
CLI: doveadm director flush 10.0.234
</nowiki>

=== doveadm director dump ===

Dumb the current director backend host configuration as commands

<nowiki>
{
"command": "directorDump",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|}

example:

<nowiki>
[
[
"directorDump",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorDump",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"command": "add",
"host": "10.0.0.234",
"socket-path": "/var/run/dovecot/director-admin",
"vhost_count": "100"
},
{
"command": "add",
"host": "10.0.0.235",
"socket-path": "/var/run/dovecot/director-admin",
"vhost_count": "100"
}
],
"bb"
]
]

CLI: doveadm director dump
</nowiki>

=== doveadm director ring add ===

add new director to director ring

parameters:

<nowiki>
{
"command": "directorRingAdd",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "ip",
"type": "string"
},
{
"name": "port",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|ip
|String
|director ip address to add
|10.0.0.233
|-
|port
|String
|port number to use if not default
|9143
|}

example:

<nowiki>
[
[
"directorRingAdd",
{
"ip": "10.0.0.233"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRingAdd",{"ip":"10.0.0.233"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director ring add 10.0.0.233
</nowiki>

=== doveadm director ring remove ===

remove director from director ring

parameters:

<nowiki>
{
"command": "directorRingRemove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "ip",
"type": "string"
},
{
"name": "port",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|ip
|String
|director ip to remove
|10.0.0.233
|-
|port
|String
|director service port if not default
|9143
|}

example:

<nowiki>
[
[
"directorRingRemove",
{
"ip": "10.0.0.233"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRingRemove",{"ip":"10.0.0.233"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director ring remove 10.0.0.233
</nowiki>

=== doveadm director ring status ===

show director ring status

parameters:

<nowiki>

{
"command": "directorRingStatus",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|}

example:

<nowiki>
[
[
"directorRingStatus",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRingStatus",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>

[
"doveadmResponse",
[
{
"director ip": "10.0.0.232",
"last failed": "never",
"port": "9143",
"status": "synced",
"type": "self"
},
{
"director ip": "10.0.0.233",
"last failed": "never",
"port": "9143",
"status": "",
"type": ""
}
],
"bb"
]
]

CLI: doveadm director ring status
</nowiki>

== doveadm proxy ==

The doveadm proxy commands are used to list or kick active Dovecot proxy connections.

=== doveadm proxy list ===

list active connections in the dovecot proxy

parameters:

<nowiki>
{
"command": "proxyList",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|}

example:

<nowiki>
[
[
"proxyList",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["proxyList",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"dest-ip": "127.0.0.1",
"dest-port": "1143",
"service": "imap",
"src-ip": "10.0.0.153",
"username": "samik"
}
],
"bb"
]
]

CLI: doveadm proxy list
</nowiki>

=== doveadm proxy kick ===

kick user session from proxy. applicable to imap/pop3/managesieve sessions

parameters:

<nowiki>
{
"command": "proxyKick",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|userid to kick
|samik
|}

example:

<nowiki>
[
[
"proxyKick",
{
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["proxyKick",{"user":"samik"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"count": "1"
}
],
"bb"
]
]

CLI: doveadm proxy kick samik
</nowiki>

== doveadm logs errors ==

fetch errors log

paraments:

<nowiki>
{
"command": "logErrors",
"parameters": [
{
"name": "since",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|}

example:

<nowiki>
[
[
"logErrors",
{},
"a2"
]
]

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

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"prefix": "stats",
"text": "Stats client input error: Invalid level",
"timestamp": "Dec 09 16:24:00",
"type": "Error"
},
{
"prefix": "doveadm(127.0.0.1)",
"text": "read(/var/run/dovecot/stats) unexpectedly disconnected",
"timestamp": "Dec 09 16:24:00",
"type": "Fatal"
},
{
"prefix": "stats",
"text": "Stats client input error: Invalid level",
"timestamp": "Dec 09 16:24:22",
"type": "Error"
},
{
"prefix": "stats",
"text": "Stats client input error: Invalid level",
"timestamp": "Dec 09 16:27:48",
"type": "Error"
},
{
"prefix": "director",
"text": "Empty server list",
"timestamp": "Dec 09 16:29:13",
"type": "Error"
},
{
"prefix": "director",
"text": "Invalid value for director_mail_servers setting",
"timestamp": "Dec 09 16:29:13",
"type": "Fatal"
}
],
"a2"
]
]

CLI: doveadm log errors
</nowiki>

== doveadm dict ==
=== doveadm dict get ===

get user key value from configured dictionary

parameters:

<nowiki>
{
"command": "dictGet",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to query
|samik
|-
|dictUri
|String
|optional URI for dictionary to query
|
|-
|key
|String
|key to query
|
|}

=== doveadm dict set ===

set user key value in configured dictionary

parameters:

<nowiki>
{
"command": "dictSet",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
},
{
"name": "value",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|samik
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|key
|String
|dictionary key to modify
|
|-
|value
|string
|value to set
|
|}

=== doveadm dict unset ===

unset user key value in configured dictionary

parameters:

<nowiki>
{
"command": "dictUnset",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|key
|String
|dictionary key to unset
|
|}
== doveadm dict inc ==

increase users key value in dictionary

parameters:

<nowiki>
{
"command": "dictInc",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
},
{
"name": "difference",
"type": "integer"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|-
|key
|String
|dictionary key to increase
|
|-
|difference
|integer
|increment value
|
|}

=== doveadm dict iter ===

list user keys in dictionary

parameters:

<nowiki>
{
"command": "dictIter",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "exact",
"type": "boolean"
},
{
"name": "recurse",
"type": "boolean"
},
{
"name": "noValue",
"type": "boolean"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "prefix",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|exact
|Boolean
|list only exact matches
|
|-
|recurce
|Boolean
|do recursive search
|
|-
|noValue
|Boolean
|list also keys that have no value set
|
|-
|prefix
|String
|search only keys with given prefix
|
|}

== doveadm fs ==
=== doveadm fs get ===

get object from storage

parameters:

<nowiki>
{
"command": "fsGet",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem to fetch
|
|}

=== doveadm fs put ===

put object to storage

parameters:

<nowiki>
{
"command": "fsPut",
"parameters": [
{
"name": "hash",
"type": "string"
},
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "inputPath",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|hash
|string
|
|
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|inputPath
|String
|source object path in local filesystem
|
|-
|path
|String
|object path filesystem to put
|
|}

=== doveadm fs copy ===

copy object in storage

parameters:

<nowiki>
{
"command": "fsCopy",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "sourcePath",
"type": "string"
},
{
"name": "destinationPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|sourcePath
|String
|source object path
|
|-
|Destination path
|String
|destination object path in filesystem
|
|}

=== doveadm fs stat ===

fetch fs driver statistics

parameters:

<nowiki>
{
"command": "fsStat",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem fetch statistics for
|
|}

=== doveadm fs metadata ===

get filesystem object metadata

parameters:

<nowiki>
{
"command": "fsMetadata",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem fetch metadata for
|
|}

=== doveadm fs delete ===

delete object from storage

<nowiki>
{
"command": "fsDelete",
"parameters": [
{
"name": "recursive",
"type": "boolean"
},
{
"name": "maxParallel",
"type": "integer"
},
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem to delete
|
|-
|recursive
|Boolean
|do a recursive delete of path
|
|-
|maxParallel
|integer
|max number of parallel workers
|
|}

=== doveadm fs iter ===

list objects in given fs path

parameters:

<nowiki>
{
"command": "fsIter",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|path in filesystem to list
|
|}

=== doveadm fs iter-dirs ===
ist subfolders in given path

parameters:

<nowiki>
{
"command": "fsIterDirs",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|path in filesystem to list for subfolders
|
|}

== doveadm auth cache flush ==

flush authentication cache for one user or all users

parameters:

<nowiki>
{
"command": "authCacheFlush",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String array
|optional list of users in flush
|[“samik”,”samitest”]
|}

example:

<nowiki>
[
[
"authCacheFlush",
{
"user": [
"samik"
]
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["authCacheFlush",{"user":["samik"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"entries": "0"
}
],
"bb"
]
]

CLI: doveadm auth cache flush samik
</nowiki>

== doveadm user ==

do a userdb lookup for an user

<nowiki>
{
"command": "user",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "authInfo",
"type": "array"
},
{
"name": "field",
"type": "string"
},
{
"name": "expandField",
"type": "string"
},
{
"name": "userdbOnly",
"type": "boolean"
},
{
"name": "userMask",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|authInfo
|String array
|auth_info specifies additional conditions for the user command. The auth_info option string has to be given as name=value pair. For multiple conditions the -x option could be supplied multiple times.
Possible names for the auth_info are:
service
The service for which the userdb lookup should be tested. The value may be the name of a service, commonly used with Dovecot. For example: imap, pop3 or smtp.
lip
The local IP address (server) for the test.
rip
The remote IP address (client) for the test.
lport
The local port, e.g. 143
rport
The remote port, e.g. 24567
|sevice=imap
|-
|field
|String
|fetch only one specified field instead of all
|
|-
|expandField
|String
|expand configuration variable with user specific values
|
|-
|userdbOnly
|Boolean
|only fetch from userdb lookup and don’t process passdb
|
|-
|userMask
|String array
|search filter
|
|}

example:

<nowiki>
[
[
"user",
{
"userMask": [
"samik"
]
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["user",{"userMask":["samik"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
{
"samik": {
"gid": "1000",
"home": "/var/vmail/samik",
"junkflag": "0",
"mail": "Maildir:/mails/mails/samik/Maildir",
"namespace/Junk/hidden": "no",
"namespace/Junk/list": "yes",
"uid": "1000"
}
},
"bb"
]
]

CLI: doveadm user samik
</nowiki>

== doveadm mailbox ==
=== doveadm mailbox metadata set ===

set user mailbox metadata

parameters:

<nowiki>
{
"command": "mailboxMetadataSet",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "key",
"type": "string"
},
{
"name": "value",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata set
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to set
|
|-
|value
|String
|metadata value to set
|
|}

example:

<nowiki>
[
[
"mailboxMetadataSet",
{
"key": "/private/comment",
"mailbox": "INBOX",
"user": "samik",
"value": "test"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataSet",{"user":"samik","mailbox":"INBOX","key":"/private/comment","value":"test"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox metadata set –u samik INBOX /private/comment test
</nowiki>

=== doveadm mailbox metadata unset ===

unset user mailbox metadata

parameters:

<nowiki>
{
"command": "mailboxMetadataUnset",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata unset
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to unset
|
|}

example:

<nowiki>
[
[
"mailboxMetadataUnset",
{
"key": "/private/comment",
"mailbox": "INBOX",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataUnset",{"user":"samik","mailbox":"INBOX","key":"/private/comment"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox metadata unset –u samik INBOX /private/comment
</nowiki>

=== doveadm mailbox metadata get ===

get user mailbox metadata

parameters:

<nowiki>
{
"command": "mailboxMetadataGet",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata get
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to get
|
|}

example:

<nowiki>
[
[
"mailboxMetadataGet",
{
"key": "/private/comment",
"mailbox": "INBOX",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataGet",{"user":"samik","mailbox":"INBOX","key":"/private/comment"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response

<nowiki>
[
[
"doveadmResponse",
[
{
"value": "plaa"
}
],
"bb"
]
]

CLI: doveadm mailbox metadata get –u samik INBOX /private/comment
</nowiki>

=== doveadm mailbox list ===

list user mailbox metadata for a folder

parameters:

<nowiki>

"command": "mailboxMetadataList",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "keyPrefix",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata get
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to get
|
|-
|keyPrefix
|String
|search prefix for keys
|
|-
|mailbox
|String
|mailbox to fetch metadata from
|
|}

example:

<nowiki>
[
[
"mailboxMetadataList",
{
"mailbox": "INBOX",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataList",{"user":"samik","mailbox":"INBOX"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"key": "comment"
},
{
"key": "specialuse"
}
],
"bb"
]
]

CLI: doveadm mailbox metadata list –u samik INBOX
</nowiki>

=== doveadm mailbox status ===

fetch user mailbox status

parameters:

<nowiki>
{
"command": "mailboxStatus",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "totalSum",
"type": "boolean"
},
{
"name": "field",
"type": "array"
},
{
"name": "mailboxMask",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply status fetch
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|totalSum
|boolean
|
|
|-
|field
|String array
|fields to fetch
|all
|-
|mailboxMask
|String array
|fetch status on given mailboxes
|
|}

example:

<nowiki>

[
[
"mailboxStatus",
{
"field": [
"all"
],
"mailboxMask": [
"INBOX",
"INBOX/*",
"*"
],
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxStatus",{"user":"samik","field":["all"],"mailboxMask":["INBOX","INBOX/*","*"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"guid": "21b588150b156558eb3500007afd792c",
"highestmodseq": "5",
"mailbox": "Junk",
"messages": "0",
"recent": "0",
"uidnext": "1",
"uidvalidity": "1483019529",
"unseen": "0",
"vsize": "0"
},
{
"guid": "21b588150b156558eb3500007afd792c",
"highestmodseq": "5",
"mailbox": "INBOX",
"messages": "0",
"recent": "0",
"uidnext": "1",
"uidvalidity": "1483019529",
"unseen": "0",
"vsize": "0"
}
],
"bb"
]
]

CLI: doveadm mailbox status –u samik all “*”
</nowiki>

=== doveadm mailbox list ===

fetch user folder list

parameters:

<nowiki>
{
"command": "mailboxList",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mutf7",
"type": "boolean"
},
{
"name": "utf8",
"type": "boolean"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "mailboxMask",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply mailbox list
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|mutf7
|Boolean
|
|
|-
|utf8
|Boolean
|fetch only certain fields instead of all
|
|-
|subscription
|Boolean
|
|
|-
|mailboxMask
|String array
|fetch list of given mailboxes
|
|}

example:

<nowiki>
[
[
"mailboxList",
{
"user": "samik"
},
"bb"
]
]
# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxList",{"user":"samik"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"mailbox": "Junk"
},
{
"mailbox": "INBOX"
}
],
"bb"
]
]

CLI: doveadm mailbox list –u samik
</nowiki>

=== doveadm mailbox create ===
create mailbox folder for user

parameters:

<nowiki>
{
"command": "mailboxCreate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "guid",
"type": "string"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply mailbox create
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|subscription
|Boolean
|
|
|-
|mailbox
|String array
|list of mailbox folders to create
|
|}

example:

<nowiki>
[
[
"mailboxCreate",
{
"mailbox": [
"INBOX/myfolder"
],
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxCreate",{"user":"samik","mailbox":["INBOX/myfolder"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>

[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox create –u samik INBOX/myfolder
</nowiki>

=== doveadm mailbox delete ===

delete user mailbox folder

parameters:

<nowiki>
{
"command": "mailboxDelete",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "requireEmpty",
"type": "boolean"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "recursive",
"type": "boolean"
},
{
"name": "unsafe",
"type": "boolean"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply delete
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|requireEmpty
|Boolean
|only delete if folder is empty
|
|-
|subscription
|Boolean
|
|
|-
|recursive
|Boolean
|delete also subfolders
|
|-
|unsafe
|Boolean
|
|
|-
|mailbox
|String array
|list of mailbox folders to create
|
|}

example:

<nowiki>
[
[
"mailboxDelete",
{
"mailbox": [
"INBOX/myfolder"
],
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxDelete",{"user":"samik","mailbox":["INBOX/myfolder"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox delete –u samik INBOX/myfolder
</nowiki>

=== doveadm mailbox rename ===

rename user folder

parameters:

<nowiki>
{
"command": "mailboxRename",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "newName",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply mailbox rename
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|subscriptions
|Boolean
|
|
|-
|newName
|String
|mailbox new name
|
|-
|mailbox
|String
|mailbox to rename
|
|}

example:

<nowiki>
[
[
"mailboxRename",
{
"mailbox": "INBOX/myfolder",
"newName": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxRename",{"user":"samik","mailbox":"INBOX/myfolder","newName":"INBOX/myfoldertoo"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox rename –u samik INBOX/myfolder INBOX/myfoldertoo
</nowiki>

=== doveadm mailbox subscribe ===

subscribe user to a mailbox

parameters:

<nowiki>
{
"command": "mailboxSubscribe",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply subscribe
|
|-
|userFile
|String
|optionally fetch usernames from. One username per line
|
|-
|mailbox
|String
|mailbox to subscribe
|
|}

example:

<nowiki>
[
[
"mailboxSubscribe",
{
"mailbox": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxSubscribe",{"user":"samik","mailbox":"INBOX/myfoldertoo"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:
<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox subscribe –u samik INBOX/myfoldertoo
</nowiki>

=== doveadm mailbox unsubscribe ===

unsubscribe user from an folder

parameters:

<nowiki>
{
"command": "mailboxUnsubscribe",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply unsubscribe
|
|-
|userFile
|String
|optionally fetch usernames from. One username per line
|
|-
|mailbox
|String
|mailbox to unsubscribe
|
|}

example:

<nowiki>
[
[
"mailboxUnsubscribe",
{
"mailbox": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxUnsubscribe",{"user":"samik","mailbox":"INBOX/myfoldertoo"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox unsubscribe –u samik INBOX/myfoldertoo
</nowiki>

=== doveadm mailbox update ===

update user mailbox information

parameters:

<nowiki>
{
"command": "mailboxUpdate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailboxGuid",
"type": "string"
},
{
"name": "uidValidity",
"type": "string"
},
{
"name": "minNextUid",
"type": "string"
},
{
"name": "minFirstRecentUid",
"type": "string"
},
{
"name": "minHighestModseq",
"type": "string"
},
{
"name": "minHighestPvtModseq",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply update
|
|-
|userFile
|String
|optionally fetch usernames from. One username per line
|
|-
|mailbox
|String
|mailbox to unsubscribe
|
|-
|mailboxGuid
|String
|set mailbox guid
|
|-
|uidValidity
|String
|set mailbox uidvalidity
|
|-
|minNextuid
|String
|set mailbox minimum next uid
|
|-
|minFirstRecentuid
|String
|set mailbox minimum recent uid
|
|-
|minHighestModseq
|String
|
|
|-
|minHighestPvtModseq
|String
|
|
|}

=== doveadm mailbox save ===

save mail into users mailbox

parameters:

<nowiki>
{
"command": "save",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "file",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to save mail into
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|mailbox
|String
|mailbox to unsubscribe
|
|-
|file
|String
|mail to inject
|
|}

example:

<nowiki>
[
[
"save",
{
"file": "From: Joulu Pukki <joulu.pukki@korvatunturi.fi>\nSubject: plaa\n\nmail body\n",
"mailbox": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["save",{"user":"samik","mailbox":"INBOX/myfoldertoo","file":"From: Joulu Pukki <joulu.pukki@korvatunturi.fi>\nSubject: plaa\n\nmail body\n"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]
</nowiki>

== doveadm fetch ==

fetch data from user mailbox

parameters:

<nowiki>
{
"command": "fetch",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "field",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to fetch data
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|field
|String array
|fields to fetch. Supported fields as of dovecot 2.2.26: hdr.<name> body.<section> binary.<section> user mailbox mailbox-guid seq uid guid flags modseq hdr body body.snippet text text.utf8 size.physical size.virtual date.received date.sent date.saved date.received.unixtime date.sent.unixtime date.saved.unixtime imap.envelope imap.body imap.bodystructure pop3.uidl pop3.order refcount storageid
|
|-
|query
|String array
|search query to user
|
|}

example:

<nowiki>
[
[
"fetch",
{
"field": [
"text"
],
"query": [
"mailbox",
"INBOX/myfoldertoo"
],
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["fetch",{"user":"samik","field":["text"],"query":["mailbox","INBOX/myfoldertoo"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"text": "From: Joulu Pukki <joulu.pukki@korvatunturi.fi>\nSubject: plaa\n\nmail body\n"
}
],
"bb"
]
]

CLI: doveadm fetch –u samik “text” mailbox INBOX/myfoldertoo
</nowiki>

== doveadm index ==

index user mailbox folder or folders

parameters:

<nowiki>
{
"command": "index",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "queue",
"type": "boolean"
},
{
"name": "maxRecent",
"type": "string"
},
{
"name": "mailboxMask",
"type": "string"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to index
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|queue
|Boolean
|queue index operation for later execution
|
|-
|maxRecent
|String
|max number of recent mails to index
|
|-
|mailboxMask
|String
|mailbox search mask to apply indexing into
|
|}

example:

<nowiki>
[
[
"index",
{
"mailboxMask": "INBOX*",
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["index",{"user":"samik","mailboxMask":"INBOX*"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm index –u samik “INBOX*”
</nowiki>

== doveadm altmove ==

move mails between primary and alternative mailbox storage locations. Applicable to mdbox and sdbox mailbox formats only

parameters:

<nowiki>
{
"command": "altmove",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "reverse",
"type": "boolean"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to apply move
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|reverse
|Boolean
|do a reverse move
|
|-
|query
|String array
|search query to apply to mail move
|
|}

example:

<nowiki>
[
[
"altmove",
{
"query": [
"mailbox",
"INBOX/myfoldertoo",
"savedbefore",
"since",
"30d"
],
"reverse": 0,
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["altmove",{"user":"samik","reverse":0,"query":["mailbox","INBOX/myfoldertoo","savedbefore","since","30d"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

== doveadm deduplicate ==

This command is used to expunge duplicated messages in mailboxes

parameters:

<nowiki>
{
"command": "deduplicate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "byMsgid",
"type": "boolean"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to deduplicate
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|byMsgId
|Boolean
|deduplicate by Message-ID instead of guid
|
|-
|query
|String array
|search query to apply to deduplicate
|
|}

== doveadm expunge ==

Expunge messages matching given search query

parameters:

<nowiki>
{
"command": "expunge",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "deleteEmptyMailbox",
"type": "boolean"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to expunge
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|deleteEmptyMailbox
|Boolean
|delete also mailbox if it’s empty after expunge has been applied
|
|-
|query
|String array
|search query to apply to expunge
|
|}

== doveadm flags ==
add, remove or replace messages' flags

=== doveadm flags add ===

add flag to a message or messages

parameters:

<nowiki>
{
"command": "flagsAdd",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "flag",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to add flags
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|flag
|String array
|list of flags to add
|
|-
|query
|String array
|search query to apply to flag add
|
|}

=== doveadm flags remove ===

remove flags from message or messages

parameters:

<nowiki>
{
"command": "flagsRemove",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "flag",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to add flags
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|flag
|String array
|list of flags to remove
|
|-
|query
|String array
|search query to apply to flag remove
|
|}

=== doveadm flags replace ===

Replace flags with another flag in message or messages. Replaces all current flags with the ones in the parameter list

parameters:

<nowiki>
{
"command": "flagsReplace",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "flag",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to replace flags
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|flag
|String array
|list of flags to replace with
|
|-
|query
|String array
|search query to apply to flag replace
|
|}

== doveadm import ==

Import messages matching given search query

parameters:

<nowiki>
{
"command": "import",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "subscribe",
"type": "boolean"
},
{
"name": "sourceLocation",
"type": "string"
},
{
"name": "destParentMailbox",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to apply import
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|subscribe
|boolean
|when enabled possible newly created folders are also subscibed
|
|-
|sourceLocation
|String
|location of source mailboxes
|
|-
|destParentMailbox
|String
|destination parent mailbox where to import
|
|-
|query
|String array
|search query for messages to import
|
|}

== doveadm force-resync ==

Under certain circumstances it may happen, that dovecot is unable to automatically solve problems with mailboxes. In such situations the force-resync command may be helpful. It tries to fix all problems. For sdbox and mdbox mailboxes the storage files will be also checked.

parameters:

<nowiki>
{
"command": "forceResync",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailboxMask",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|user
|String
|uid of user to apply resync
|
|-
|mailboxMask
|String
|apply forced resync on given mailboxes
|INBOX*
|}

example:

<nowiki>
[
[
"forceResync",
{
"mailboxMask": "INBOX*",
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["forceResync",{"user":"samik","mailboxMask":"INBOX*"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm force-resync –u samik “INBOX*”
</nowiki>

== doveadm purge ==

Remove messages with refcount=0 from mdbox files

parameters:

<nowiki>
{
"command": "purge",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to apply purge
|
|}

== doveadm search ==

Show a list of mailbox GUIDs and message UIDs matching given search query

parameters:

<nowiki>
{
"command": "search",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|user
|String
|uid of user to apply purge
|
|-
|query
|String array
|search query
|
|}

example:

<nowiki>
[
[
"search",
{
"query": [
"mailbox",
"INBOX*",
"all"
],
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["search",{"user":"samik","query":["mailbox","INBOX*","all"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"mailbox-guid": "cf497f128caf7c58612200007afd792c",
"uid": "1"
}
],
"bb"
]
]

CLI: doveadm search –u samik mailbox “INBOX*” all
</nowiki>

== doveadm copy ==

Copy messages matching the given search query into another mailbox

parameters:

<nowiki>
{
"command": "copy",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "destinationMailbox",
"type": "string"
},
{
"name": "sourceType",
"type": "string"
},
{
"name": "sourceUser",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm move ==

Move messages matching the given search query into another mailbox

parameters:

<nowiki>
{
"command": "move",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "destinationMailbox",
"type": "string"
},
{
"name": "sourceType",
"type": "string"
},
{
"name": "sourceUser",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm fscache rescan ==

force fscache rescan

parameters:

<nowiki>
{
"command": "fscacheRescan",
"parameters": [
{
"name": "path",
"type": "string"
},
{
"name": "maxAge",
"type": "integer"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm metacache ==
=== doveadm metacache clean ===

clean metacache content for given user or all users

parameters:

<nowiki>
{

"command": "metacacheClean",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "days",
"type": "integer"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache flush ===

flush metacache contents to storage for given user or all users

parameters:

<nowiki>
{
"command": "metacacheFlush",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache unpack ===

unpack metacache index bundle to target directory

parameters:

<nowiki>
{
"command": "metacacheUnpack",
"parameters": [
{
"name": "bundleName",
"type": "string"
},
{
"name": "bundle",
"type": "string"
},
{
"name": "destinationDirectory",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache flushall ===

flush metacache to storage for all users

parameters:

<nowiki>
{
"command": "metacacheFlushall",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache remove ===

remove metacache for given mask

parameters:

<nowiki>
{
"command": "metacacheRemove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "mask",
"type": "string"
}
]
}
</nowiki>
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache list ===

list local metacache contents

parameters:

<nowiki>
{
"command": "metacacheList",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm obox user delete ==

delete user data from storage, Cassandra and local caches (metacache and fscache).

parameters:

<nowiki>
{
"command": "oboxUserDelete",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

example:

<nowiki>
[
[
"oboxUserDelete",
{
"allUsers": 0,
"socketPath": "",
"user": "testuser003",
"userFile": ""
},
"aa"
]
]

# curl -v -u doveadm:hellodoveadm -X POST http://localhost:ype: application/json" -d '[["oboxUserDelete", {"allUsers":0,"user":"testuser003"}, "aa"]]'
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"aa"
]
]

CLI: doveadm obox user delete –u testuser003
</nowiki>

== doveadm sieve ==

Commands related to handling Sieve scripts.

=== doveadm sieve list ===

list user sieve scripts

parameters:

<nowiki>
{
"command": "sieveList",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve get ===

get user sieve script

parameters:

<nowiki>
{
"command": "sieveGet",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "scriptname",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve put ===

inject sieve script to user

parameters:

<nowiki>
{
"command": "sievePut",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "activate",
"type": "boolean"
},
{
"name": "scriptname",
"type": "string"
},
{
"name": "file",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve delete ===

delete user sieve

parameters:

<nowiki>
{
"command": "sieveDelete",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "ignoreActive",
"type": "boolean"
},
{
"name": "scriptname",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve activate ===

activate user sieve script

parameters:

<nowiki>
{
"command": "sieveActivate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "scriptname",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve deactivate ===

deactivate user sieve

parameters:

<nowiki>
{
"command": "sieveDeactivate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve rename ===

rename user sieve script

parameters:

<nowiki>
{
"command": "sieveRename",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "oldname",
"type": "string"
},
{
"name": "newname",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm fts ==
Dovecot fts indexing commands.

=== doveadm fts lookup ===

query user fts indexed data

parameters:

<nowiki>
{
"command": "ftsLookup",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts expand ===

<nowiki>
{
"command": "ftsExpand",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts tokenize ===

<nowiki>
{
"command": "ftsTokenize",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "language",
"type": "string"
},
{
"name": "text",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts optimize ===

<nowiki>
{
"command": "ftsOptimize",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts rescan ===

<nowiki>
{
"command": "ftsRescan",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

Template:DoveadmHTTPapi

2017-03-15T12:41:30Z

Oskarikentta: /* doveadm index */

== Table of Contents ==
__TOC__

== 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:

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

=== 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:

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

Basic auth usage:
<nowiki>
curl -H "Authorization: Basic <base64 doveadm:doveadm_password>"
http://host:port/doveadm/v1
</nowiki>
or by letting curl to form the base64 encoded authentication basig authentication header:

<nowiki>
curl –u doveadm:password http://host:port/doveadm/v1
</nowiki>

=== 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:

<nowiki>

[
[
"command1",
{
"parameter1": "value",
"parameter2": "value",
"parameter3": "value"
},
"identifier"
]
]
</nowiki>
Multiple commands can be submitted in one json payload:
<nowiki>
[
[
"command1",
{
"parameter1": "value",
"parameter2": "value"
},
"identifier1"
],
[
"command2",
{
"parameter1": "value",
"parameter2": "value"
},
"identifier2"
]
]
</nowiki>

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:

<nowiki>

son payload:

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

</nowiki>

submitting the command with curl:

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

command line equivalent

doveadm reload

=== successful response ===

<nowiki>

[
[
"doveadmResponse",
[],
"a2"
]
]
</nowiki>

=== failure response ===

<nowiki>

[
[
"error",
{
"exitCode": 68,
"type": "exitCode"
},
"a2"
]
</nowiki>

=== failure codes ===

{| class="wikitable"
|-
|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
|}

== Supported commands ==

== doveadm service ==
=== doveadm service stop ===

stop one or more dovecot services on target host

<nowiki>
{
"command": "serviceStop",
"parameters": [
{
"name": "service",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|service
|string array
|Name of service to stop
|[“imap”,”imap-hibernate”]
|}

example:

<nowiki>
[
[
"serviceStop",
{
"service": [
"imap",
"imap-hibernate"
]
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["serviceStop",{"service":["imap","imap-hibernate"]},"aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm service stop imap imap-hibernate
</nowiki>

=== doveadm stop ===

stop dovecot on the target host
<nowiki>

{
"command": "stop",
"parameters": []
}

no parameters
</nowiki>
example:
<nowiki>
[
[
"stop",
{},
"a1"
]
]

# curl -u doveadm:hellodoveadm -X POST http://localhost:8080/doveadm/v1 -H "Content-Type: application/json" -d '[["stop",{},"a1"]]'

CLI: doveadm stop
</nowiki>

=== doveadm reload ===

reload dovecot configuration

<nowiki>
{
"command": "reload",
"parameters": []
}
</nowiki>

example:

<nowiki>
[
[
"reload",
{},
"a2"
]
]

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

CLI: doveadm reload
</nowiki>

== doveadm stats ==
=== doveadm stats dump ===

dump collected dovecot statistics

<nowiki>
{
"command": "statsDump",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "type",
"type": "string"
},
{
"name": "filter",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|+parameters
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|type
|String
|Type of stats to dump
|global
|-
|filter
|String
|Dump filter
|last_update 1483101542
|}

Example:

<nowiki>
[
[
"statsDump",
{
"type": "global"
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["statsDump",{"type":"global"},"aa"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"auth_cache_hits": "0",
"auth_cache_misses": "0",
"auth_db_tempfails": "0",
"auth_failures": "0",
"auth_master_successes": "0",
"auth_successes": "0",
"clock_time": "0.0",
"disk_input": "0",
"disk_output": "0",
"fscache_read": "0",
"fscache_stat": "0",
"fscache_write": "0",
"idx_del": "0",
"idx_iter": "0",
"idx_read": "0",
"idx_read_usecs": "0",
"idx_wbytes": "0",
"idx_write": "0",
"idx_write_usecs": "0",
"invol_cs": "0",
"last_update": "0.000000",
"mail_cache_hits": "0",
"mail_lookup_attr": "0",
"mail_lookup_path": "0",
"mail_read_bytes": "0",
"mail_read_count": "0",
"maj_faults": "0",
"min_faults": "0",
"num_cmds": "0",
"num_connected_sessions": "0",
"num_logins": "0",
"obox_copy": "0",
"obox_del": "0",
"obox_iter": "0",
"obox_read": "0",
"obox_read_usecs": "0",
"obox_stat": "0",
"obox_wbytes": "0",
"obox_write": "0",
"obox_write_usecs": "0",
"read_bytes": "0",
"read_count": "0",
"reset_timestamp": "1483104199",
"sys_cpu": "0.0",
"user_cpu": "0.0",
"vol_cs": "0",
"write_bytes": "0",
"write_count": "0"
}
],
"aa"
]
]

CLI: doveadm stats dump global
</nowiki>

=== doveadm stats reset ===
reset dovecot statistics counters
<nowiki>

{
"command": "statsReset",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|}

example:

<nowiki>
[
[
"statsReset",
{},
"aa"
]
]

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

CLI: doveadm stats reset
</nowiki>

== doveadm penalty ==

<nowiki>
show current penalties

{
"command": "penalty",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "netmask",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|string
|Path to doveadm socket
|/var/run/dovecot-server
|-
|netmask
|string
|To reduce/filter the output supply an IP address or a network range in CIDR notation (ip/mask)
|10.0.0.0/24
|}

example:

<nowiki>
[
[
"penalty",
{},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["penalty",{},"aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm penalty
</nowiki>

== doveadm kick ==

Kick user from dovecot. Applicable to session in dovecot backend only

<nowiki>
{
"command": "kick",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "force",
"type": "boolean"
},
{
"name": "mask",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|force
|Boolean
|Do a forced kick?
|0
|-
|mask
|String
|Uid mask
|testuser001
|}

example:

<nowiki>
[
[
"kick",
{
"force": 0,
"mask": "testuser001"
},
"aa"
]
]

# curl -v -u doveadm:hellodoveadm –H “Content-Type: application/json" -d '[["kick", {"mask":"testuser001"}, "aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm kick testuser001
</nowiki>

response for succesfull kick:

<nowiki>
[
[
"doveadmResponse",
[
{
"result": "testuser001"
}
],
"aa"
]
]
</nowiki>

response in case kick failed:

<nowiki>
[
[
"error",
{
"exitCode": 68,
"type": "exitCode"
},
"aa"
]
]
</nowiki>

== doveadm who ==

<nowiki>
list active dovecot sessions

{
"command": "who",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "separateConnections",
"type": "boolean"
},
{
"name": "mask",
"type": "array"
}
]
}
</nowiki>

parameters

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|string
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|separateConnections
|Boolean
|Show each user connection in separate entries
|0
|-
|mask
|string array
|Uid mask
|testuser001
|}

Example:

<nowiki>
[
[
"who",
{
"mask": "",
"separateConnections": 0,
"socketPath": ""
},
"aa"
]
]

# curl -v -u doveadm:hellodoveadm -X POST http://localhost:ype: application/json" -d '[["who", {}, "aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm who
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"connections": "1",
"ips": "(127.0.0.1)",
"pids": "(4999)",
"service": "imap",
"username": "testuser001"
}
],
"aa"
]
]
</nowiki>

== doveadm director ==
=== doveadm director status ===

Show backend statuses on directors. Available only in directors

<nowiki>
[
{
"command": "directorStatus",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "tag",
"type": "string"
}
]
}
]
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|String
|Show director status for Tagged hosts only
|NewBackend
|}

example:

<nowiki>
[
[
"directorStatus",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorStatus",{},"bb"]]' http://localhost:8080/doveadm/v1

</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"mail server ip": "10.0.0.234",
"state": "up",
"state-changed": "2016-12-15 08:31:37",
"tag": "",
"users": "1",
"vhosts": "100"
},
{
"mail server ip": "10.0.0.235",
"state": "up",
"state-changed": "2016-12-15 08:31:04",
"tag": "",
"users": "0",
"vhosts": "100"
}
],
"bb"
]
]

CLI: doveadm director status
</nowiki>

=== doveadm director map ===

list current user → host mappings. Applicable to director only

<nowiki>

"command": "directorMap",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "usersFile",
"type": "string"
},
{
"name": "hashMap",
"type": "boolean"
},
{
"name": "userMap",
"type": "boolean"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

parameters

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|usersFile
|String
|provide Path to users list. One username per line
|/etc/dovecot/userlist.txt
|-
|hashMap
|Boolean
|Output users as hashmap
|True
|-
|userMap
|Boolean
|Output users as userlist
|True
|-
|host
|String
|Show only mappings to given host
|10.0.0.234
|}

example:

<nowiki>
[
[
"directorMap",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorMap",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"expire time": "2016-12-30 14:52:56",
"hash": "3853430566",
"mail server ip": "10.0.0.235",
"user": "samik"
}
],
"bb"
]
]

CLI: doveadm director map
</nowiki>

=== doveadm director add ===

add backend to director ring

<nowiki>
{
"command": "directorAdd",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "tag",
"type": "string"
},
{
"name": "host",
"type": "string"
},
{
"name": "vhostCount",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|tag
|String
|apply tag to backend
|/etc/dovecot/userlist.txt
|-
|host
|String
|backend ip to add
|10.0.0.234
|-
|vhostCount
|String
|vhost count to add
|100
|}

Example:

<nowiki>
[
[
"directorAdd",
{
"host": "10.0.234"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorAdd",{"host":"10.0.234"},"bb"]]' http://localhost:8080/doveadm/v1

CLI: doveadm director add 10.0.0.234
</nowiki>

=== doveadm director update ===

<nowiki>
{
"command": "directorUpdate",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
},
{
"name": "vhostCount",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|string
|Show director status for tagged hosts only
|NewBackend
|}

=== doveadm director up ===

<nowiki>
{
"command": "directorUp",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|string
|Show director status for tagged hosts only
|NewBackend
|}

=== doveadm director down ===

<nowiki>
{
"command": "directorDown",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|string
|Show director status for tagged hosts only
|NewBackend
|}

=== doveadm director remove ===

remove backend from director ring

<nowiki>
{
"command": "directorRemove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|host
|String
|backend to remove
|10.0.0.134
|}

example:

<nowiki>
[
[
"directorRemove",
{
"host": "10.0.0.234"
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRemove",{"host":"10.0.0.234"},"aa"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"aa"
]
]

CLI: doveadm director remove 10.0.0.234
</nowiki>

=== doveadm director move ===

move user mapping from backend to another or create director mapping for an user
<nowiki>
{
"command": "directorMove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|user
|String
|User uid to move
|testuser001
|-
|host
|string
|Target backend ip as listed in doveadm doveadm director status
|10.0.0.234
|}

example:

<nowiki>
[
[
"directorMove",
{
"host": "10.0.234",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorMove",{"user":"samik","host":"10.0.234"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director move samik 10.0.0.234
</nowiki>

== doveadm director kick ==

<nowiki>
{
"command": "directorKick",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|user
|String
|uid of user to kick
|samik
|}

example:

<nowiki>
[
[
"directorKick",
{
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorKick",{"user":"samik"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director kick samik
</nowiki>

=== doveadm director flush ===

flush connection mappings to one backend at director level. All users mapped to given host will be flushed from the hashmap table and will be redistributed to backends.

Parameters:

<nowiki>
{
"command": "directorFlush",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "forceFlush",
"type": "boolean"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|forceFlush
|Boolean
|Flag to make flush forced
|True
|-
|host
|String
|Backend ip address from doveadm director status list
|10.0.0.234
|}

example:

<nowiki>
[
[
"directorFlush",
{
"host": "10.0.0.234"
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorFlush",{"host":"10.0.0.234"},"aa"]]' http://localhost:8080/doveadm/v1

</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"aa"
]
]
CLI: doveadm director flush 10.0.234
</nowiki>

=== doveadm director dump ===

Dumb the current director backend host configuration as commands

<nowiki>
{
"command": "directorDump",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|}

example:

<nowiki>
[
[
"directorDump",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorDump",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"command": "add",
"host": "10.0.0.234",
"socket-path": "/var/run/dovecot/director-admin",
"vhost_count": "100"
},
{
"command": "add",
"host": "10.0.0.235",
"socket-path": "/var/run/dovecot/director-admin",
"vhost_count": "100"
}
],
"bb"
]
]

CLI: doveadm director dump
</nowiki>

=== doveadm director ring add ===

add new director to director ring

parameters:

<nowiki>
{
"command": "directorRingAdd",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "ip",
"type": "string"
},
{
"name": "port",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|ip
|String
|director ip address to add
|10.0.0.233
|-
|port
|String
|port number to use if not default
|9143
|}

example:

<nowiki>
[
[
"directorRingAdd",
{
"ip": "10.0.0.233"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRingAdd",{"ip":"10.0.0.233"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director ring add 10.0.0.233
</nowiki>

=== doveadm director ring remove ===

remove director from director ring

parameters:

<nowiki>
{
"command": "directorRingRemove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "ip",
"type": "string"
},
{
"name": "port",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|ip
|String
|director ip to remove
|10.0.0.233
|-
|port
|String
|director service port if not default
|9143
|}

example:

<nowiki>
[
[
"directorRingRemove",
{
"ip": "10.0.0.233"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRingRemove",{"ip":"10.0.0.233"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director ring remove 10.0.0.233
</nowiki>

=== doveadm director ring status ===

show director ring status

parameters:

<nowiki>

{
"command": "directorRingStatus",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|}

example:

<nowiki>
[
[
"directorRingStatus",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRingStatus",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>

[
"doveadmResponse",
[
{
"director ip": "10.0.0.232",
"last failed": "never",
"port": "9143",
"status": "synced",
"type": "self"
},
{
"director ip": "10.0.0.233",
"last failed": "never",
"port": "9143",
"status": "",
"type": ""
}
],
"bb"
]
]

CLI: doveadm director ring status
</nowiki>

== doveadm proxy ==

The doveadm proxy commands are used to list or kick active Dovecot proxy connections.

=== doveadm proxy list ===

list active connections in the dovecot proxy

parameters:

<nowiki>
{
"command": "proxyList",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|}

example:

<nowiki>
[
[
"proxyList",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["proxyList",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"dest-ip": "127.0.0.1",
"dest-port": "1143",
"service": "imap",
"src-ip": "10.0.0.153",
"username": "samik"
}
],
"bb"
]
]

CLI: doveadm proxy list
</nowiki>

=== doveadm proxy kick ===

kick user session from proxy. applicable to imap/pop3/managesieve sessions

parameters:

<nowiki>
{
"command": "proxyKick",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|userid to kick
|samik
|}

example:

<nowiki>
[
[
"proxyKick",
{
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["proxyKick",{"user":"samik"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"count": "1"
}
],
"bb"
]
]

CLI: doveadm proxy kick samik
</nowiki>

== doveadm logs errors ==

fetch errors log

paraments:

<nowiki>
{
"command": "logErrors",
"parameters": [
{
"name": "since",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|}

example:

<nowiki>
[
[
"logErrors",
{},
"a2"
]
]

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

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"prefix": "stats",
"text": "Stats client input error: Invalid level",
"timestamp": "Dec 09 16:24:00",
"type": "Error"
},
{
"prefix": "doveadm(127.0.0.1)",
"text": "read(/var/run/dovecot/stats) unexpectedly disconnected",
"timestamp": "Dec 09 16:24:00",
"type": "Fatal"
},
{
"prefix": "stats",
"text": "Stats client input error: Invalid level",
"timestamp": "Dec 09 16:24:22",
"type": "Error"
},
{
"prefix": "stats",
"text": "Stats client input error: Invalid level",
"timestamp": "Dec 09 16:27:48",
"type": "Error"
},
{
"prefix": "director",
"text": "Empty server list",
"timestamp": "Dec 09 16:29:13",
"type": "Error"
},
{
"prefix": "director",
"text": "Invalid value for director_mail_servers setting",
"timestamp": "Dec 09 16:29:13",
"type": "Fatal"
}
],
"a2"
]
]

CLI: doveadm log errors
</nowiki>

== doveadm dict ==
=== doveadm dict get ===

get user key value from configured dictionary

parameters:

<nowiki>
{
"command": "dictGet",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to query
|samik
|-
|dictUri
|String
|optional URI for dictionary to query
|
|-
|key
|String
|key to query
|
|}

=== doveadm dict set ===

set user key value in configured dictionary

parameters:

<nowiki>
{
"command": "dictSet",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
},
{
"name": "value",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|samik
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|key
|String
|dictionary key to modify
|
|-
|value
|string
|value to set
|
|}

=== doveadm dict unset ===

unset user key value in configured dictionary

parameters:

<nowiki>
{
"command": "dictUnset",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|key
|String
|dictionary key to unset
|
|}
== doveadm dict inc ==

increase users key value in dictionary

parameters:

<nowiki>
{
"command": "dictInc",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
},
{
"name": "difference",
"type": "integer"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|-
|key
|String
|dictionary key to increase
|
|-
|difference
|integer
|increment value
|
|}

=== doveadm dict iter ===

list user keys in dictionary

parameters:

<nowiki>
{
"command": "dictIter",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "exact",
"type": "boolean"
},
{
"name": "recurse",
"type": "boolean"
},
{
"name": "noValue",
"type": "boolean"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "prefix",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|exact
|Boolean
|list only exact matches
|
|-
|recurce
|Boolean
|do recursive search
|
|-
|noValue
|Boolean
|list also keys that have no value set
|
|-
|prefix
|String
|search only keys with given prefix
|
|}

== doveadm fs ==
=== doveadm fs get ===

get object from storage

parameters:

<nowiki>
{
"command": "fsGet",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem to fetch
|
|}

=== doveadm fs put ===

put object to storage

parameters:

<nowiki>
{
"command": "fsPut",
"parameters": [
{
"name": "hash",
"type": "string"
},
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "inputPath",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|hash
|string
|
|
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|inputPath
|String
|source object path in local filesystem
|
|-
|path
|String
|object path filesystem to put
|
|}

=== doveadm fs copy ===

copy object in storage

parameters:

<nowiki>
{
"command": "fsCopy",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "sourcePath",
"type": "string"
},
{
"name": "destinationPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|sourcePath
|String
|source object path
|
|-
|Destination path
|String
|destination object path in filesystem
|
|}

=== doveadm fs stat ===

fetch fs driver statistics

parameters:

<nowiki>
{
"command": "fsStat",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem fetch statistics for
|
|}

=== doveadm fs metadata ===

get filesystem object metadata

parameters:

<nowiki>
{
"command": "fsMetadata",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem fetch metadata for
|
|}

=== doveadm fs delete ===

delete object from storage

<nowiki>
{
"command": "fsDelete",
"parameters": [
{
"name": "recursive",
"type": "boolean"
},
{
"name": "maxParallel",
"type": "integer"
},
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem to delete
|
|-
|recursive
|Boolean
|do a recursive delete of path
|
|-
|maxParallel
|integer
|max number of parallel workers
|
|}

=== doveadm fs iter ===

list objects in given fs path

parameters:

<nowiki>
{
"command": "fsIter",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|path in filesystem to list
|
|}

=== doveadm fs iter-dirs ===
ist subfolders in given path

parameters:

<nowiki>
{
"command": "fsIterDirs",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|path in filesystem to list for subfolders
|
|}

== doveadm auth cache flush ==

flush authentication cache for one user or all users

parameters:

<nowiki>
{
"command": "authCacheFlush",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String array
|optional list of users in flush
|[“samik”,”samitest”]
|}

example:

<nowiki>
[
[
"authCacheFlush",
{
"user": [
"samik"
]
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["authCacheFlush",{"user":["samik"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"entries": "0"
}
],
"bb"
]
]

CLI: doveadm auth cache flush samik
</nowiki>

== doveadm user ==

do a userdb lookup for an user

<nowiki>
{
"command": "user",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "authInfo",
"type": "array"
},
{
"name": "field",
"type": "string"
},
{
"name": "expandField",
"type": "string"
},
{
"name": "userdbOnly",
"type": "boolean"
},
{
"name": "userMask",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|authInfo
|String array
|auth_info specifies additional conditions for the user command. The auth_info option string has to be given as name=value pair. For multiple conditions the -x option could be supplied multiple times.
Possible names for the auth_info are:
service
The service for which the userdb lookup should be tested. The value may be the name of a service, commonly used with Dovecot. For example: imap, pop3 or smtp.
lip
The local IP address (server) for the test.
rip
The remote IP address (client) for the test.
lport
The local port, e.g. 143
rport
The remote port, e.g. 24567
|sevice=imap
|-
|field
|String
|fetch only one specified field instead of all
|
|-
|expandField
|String
|expand configuration variable with user specific values
|
|-
|userdbOnly
|Boolean
|only fetch from userdb lookup and don’t process passdb
|
|-
|userMask
|String array
|search filter
|
|}

example:

<nowiki>
[
[
"user",
{
"userMask": [
"samik"
]
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["user",{"userMask":["samik"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
{
"samik": {
"gid": "1000",
"home": "/var/vmail/samik",
"junkflag": "0",
"mail": "Maildir:/mails/mails/samik/Maildir",
"namespace/Junk/hidden": "no",
"namespace/Junk/list": "yes",
"uid": "1000"
}
},
"bb"
]
]

CLI: doveadm user samik
</nowiki>

== doveadm mailbox ==
=== doveadm mailbox metadata set ===

set user mailbox metadata

parameters:

<nowiki>
{
"command": "mailboxMetadataSet",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "key",
"type": "string"
},
{
"name": "value",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata set
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to set
|
|-
|value
|String
|metadata value to set
|
|}

example:

<nowiki>
[
[
"mailboxMetadataSet",
{
"key": "/private/comment",
"mailbox": "INBOX",
"user": "samik",
"value": "test"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataSet",{"user":"samik","mailbox":"INBOX","key":"/private/comment","value":"test"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox metadata set –u samik INBOX /private/comment test
</nowiki>

=== doveadm mailbox metadata unset ===

unset user mailbox metadata

parameters:

<nowiki>
{
"command": "mailboxMetadataUnset",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata unset
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to unset
|
|}

example:

<nowiki>
[
[
"mailboxMetadataUnset",
{
"key": "/private/comment",
"mailbox": "INBOX",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataUnset",{"user":"samik","mailbox":"INBOX","key":"/private/comment"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox metadata unset –u samik INBOX /private/comment
</nowiki>

=== doveadm mailbox metadata get ===

get user mailbox metadata

parameters:

<nowiki>
{
"command": "mailboxMetadataGet",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata get
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to get
|
|}

example:

<nowiki>
[
[
"mailboxMetadataGet",
{
"key": "/private/comment",
"mailbox": "INBOX",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataGet",{"user":"samik","mailbox":"INBOX","key":"/private/comment"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response

<nowiki>
[
[
"doveadmResponse",
[
{
"value": "plaa"
}
],
"bb"
]
]

CLI: doveadm mailbox metadata get –u samik INBOX /private/comment
</nowiki>

=== doveadm mailbox list ===

list user mailbox metadata for a folder

parameters:

<nowiki>

"command": "mailboxMetadataList",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "keyPrefix",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata get
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to get
|
|-
|keyPrefix
|String
|search prefix for keys
|
|-
|mailbox
|String
|mailbox to fetch metadata from
|
|}

example:

<nowiki>
[
[
"mailboxMetadataList",
{
"mailbox": "INBOX",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataList",{"user":"samik","mailbox":"INBOX"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"key": "comment"
},
{
"key": "specialuse"
}
],
"bb"
]
]

CLI: doveadm mailbox metadata list –u samik INBOX
</nowiki>

=== doveadm mailbox status ===

fetch user mailbox status

parameters:

<nowiki>
{
"command": "mailboxStatus",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "totalSum",
"type": "boolean"
},
{
"name": "field",
"type": "array"
},
{
"name": "mailboxMask",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply status fetch
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|totalSum
|boolean
|
|
|-
|field
|String array
|fields to fetch
|all
|-
|mailboxMask
|String array
|fetch status on given mailboxes
|
|}

example:

<nowiki>

[
[
"mailboxStatus",
{
"field": [
"all"
],
"mailboxMask": [
"INBOX",
"INBOX/*",
"*"
],
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxStatus",{"user":"samik","field":["all"],"mailboxMask":["INBOX","INBOX/*","*"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"guid": "21b588150b156558eb3500007afd792c",
"highestmodseq": "5",
"mailbox": "Junk",
"messages": "0",
"recent": "0",
"uidnext": "1",
"uidvalidity": "1483019529",
"unseen": "0",
"vsize": "0"
},
{
"guid": "21b588150b156558eb3500007afd792c",
"highestmodseq": "5",
"mailbox": "INBOX",
"messages": "0",
"recent": "0",
"uidnext": "1",
"uidvalidity": "1483019529",
"unseen": "0",
"vsize": "0"
}
],
"bb"
]
]

CLI: doveadm mailbox status –u samik all “*”
</nowiki>

=== doveadm mailbox list ===

fetch user folder list

parameters:

<nowiki>
{
"command": "mailboxList",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mutf7",
"type": "boolean"
},
{
"name": "utf8",
"type": "boolean"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "mailboxMask",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply mailbox list
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|mutf7
|Boolean
|
|
|-
|utf8
|Boolean
|fetch only certain fields instead of all
|
|-
|subscription
|Boolean
|
|
|-
|mailboxMask
|String array
|fetch list of given mailboxes
|
|}

example:

<nowiki>
[
[
"mailboxList",
{
"user": "samik"
},
"bb"
]
]
# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxList",{"user":"samik"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"mailbox": "Junk"
},
{
"mailbox": "INBOX"
}
],
"bb"
]
]

CLI: doveadm mailbox list –u samik
</nowiki>

=== doveadm mailbox create ===
create mailbox folder for user

parameters:

<nowiki>
{
"command": "mailboxCreate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "guid",
"type": "string"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply mailbox create
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|subscription
|Boolean
|
|
|-
|mailbox
|String array
|list of mailbox folders to create
|
|}

example:

<nowiki>
[
[
"mailboxCreate",
{
"mailbox": [
"INBOX/myfolder"
],
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxCreate",{"user":"samik","mailbox":["INBOX/myfolder"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>

[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox create –u samik INBOX/myfolder
</nowiki>

=== doveadm mailbox delete ===

delete user mailbox folder

parameters:

<nowiki>
{
"command": "mailboxDelete",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "requireEmpty",
"type": "boolean"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "recursive",
"type": "boolean"
},
{
"name": "unsafe",
"type": "boolean"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply delete
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|requireEmpty
|Boolean
|only delete if folder is empty
|
|-
|subscription
|Boolean
|
|
|-
|recursive
|Boolean
|delete also subfolders
|
|-
|unsafe
|Boolean
|
|
|-
|mailbox
|String array
|list of mailbox folders to create
|
|}

example:

<nowiki>
[
[
"mailboxDelete",
{
"mailbox": [
"INBOX/myfolder"
],
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxDelete",{"user":"samik","mailbox":["INBOX/myfolder"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox delete –u samik INBOX/myfolder
</nowiki>

=== doveadm mailbox rename ===

rename user folder

parameters:

<nowiki>
{
"command": "mailboxRename",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "newName",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply mailbox rename
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|subscriptions
|Boolean
|
|
|-
|newName
|String
|mailbox new name
|
|-
|mailbox
|String
|mailbox to rename
|
|}

example:

<nowiki>
[
[
"mailboxRename",
{
"mailbox": "INBOX/myfolder",
"newName": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxRename",{"user":"samik","mailbox":"INBOX/myfolder","newName":"INBOX/myfoldertoo"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox rename –u samik INBOX/myfolder INBOX/myfoldertoo
</nowiki>

=== doveadm mailbox subscribe ===

subscribe user to a mailbox

parameters:

<nowiki>
{
"command": "mailboxSubscribe",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply subscribe
|
|-
|userFile
|String
|optionally fetch usernames from. One username per line
|
|-
|mailbox
|String
|mailbox to subscribe
|
|}

example:

<nowiki>
[
[
"mailboxSubscribe",
{
"mailbox": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxSubscribe",{"user":"samik","mailbox":"INBOX/myfoldertoo"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:
<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox subscribe –u samik INBOX/myfoldertoo
</nowiki>

=== doveadm mailbox unsubscribe ===

unsubscribe user from an folder

parameters:

<nowiki>
{
"command": "mailboxUnsubscribe",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply unsubscribe
|
|-
|userFile
|String
|optionally fetch usernames from. One username per line
|
|-
|mailbox
|String
|mailbox to unsubscribe
|
|}

example:

<nowiki>
[
[
"mailboxUnsubscribe",
{
"mailbox": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxUnsubscribe",{"user":"samik","mailbox":"INBOX/myfoldertoo"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox unsubscribe –u samik INBOX/myfoldertoo
</nowiki>

=== doveadm mailbox update ===

update user mailbox information

parameters:

<nowiki>
{
"command": "mailboxUpdate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailboxGuid",
"type": "string"
},
{
"name": "uidValidity",
"type": "string"
},
{
"name": "minNextUid",
"type": "string"
},
{
"name": "minFirstRecentUid",
"type": "string"
},
{
"name": "minHighestModseq",
"type": "string"
},
{
"name": "minHighestPvtModseq",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply update
|
|-
|userFile
|String
|optionally fetch usernames from. One username per line
|
|-
|mailbox
|String
|mailbox to unsubscribe
|
|-
|mailboxGuid
|String
|set mailbox guid
|
|-
|uidValidity
|String
|set mailbox uidvalidity
|
|-
|minNextuid
|String
|set mailbox minimum next uid
|
|-
|minFirstRecentuid
|String
|set mailbox minimum recent uid
|
|-
|minHighestModseq
|String
|
|
|-
|minHighestPvtModseq
|String
|
|
|}

=== doveadm mailbox save ===

save mail into users mailbox

parameters:

<nowiki>
{
"command": "save",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "file",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to save mail into
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|mailbox
|String
|mailbox to unsubscribe
|
|-
|file
|String
|mail to inject
|
|}

example:

<nowiki>
[
[
"save",
{
"file": "From: Joulu Pukki <joulu.pukki@korvatunturi.fi>\nSubject: plaa\n\nmail body\n",
"mailbox": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["save",{"user":"samik","mailbox":"INBOX/myfoldertoo","file":"From: Joulu Pukki <joulu.pukki@korvatunturi.fi>\nSubject: plaa\n\nmail body\n"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]
</nowiki>

== doveadm fetch ==

fetch data from user mailbox

parameters:

<nowiki>
{
"command": "fetch",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "field",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to fetch data
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|field
|String array
|fields to fetch. Supported fields as of dovecot 2.2.26: hdr.<name> body.<section> binary.<section> user mailbox mailbox-guid seq uid guid flags modseq hdr body body.snippet text text.utf8 size.physical size.virtual date.received date.sent date.saved date.received.unixtime date.sent.unixtime date.saved.unixtime imap.envelope imap.body imap.bodystructure pop3.uidl pop3.order refcount storageid
|
|-
|query
|String array
|search query to user
|
|}

example:

<nowiki>
[
[
"fetch",
{
"field": [
"text"
],
"query": [
"mailbox",
"INBOX/myfoldertoo"
],
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["fetch",{"user":"samik","field":["text"],"query":["mailbox","INBOX/myfoldertoo"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"text": "From: Joulu Pukki <joulu.pukki@korvatunturi.fi>\nSubject: plaa\n\nmail body\n"
}
],
"bb"
]
]

CLI: doveadm fetch –u samik “text” mailbox INBOX/myfoldertoo
</nowiki>

== doveadm index ==

index user mailbox folder or folders

parameters:

<nowiki>
{
"command": "index",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "queue",
"type": "boolean"
},
{
"name": "maxRecent",
"type": "string"
},
{
"name": "mailboxMask",
"type": "string"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to index
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|queue
|Boolean
|queue index operation for later execution
|
|-
|maxRecent
|String
|max number of recent mails to index
|
|-
|mailboxMask
|String
|mailbox search mask to apply indexing into
|
|}

example:

<nowiki>
[
[
"index",
{
"mailboxMask": "INBOX*",
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["index",{"user":"samik","mailboxMask":"INBOX*"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm index –u samik “INBOX*”
</nowiki>

== doveadm altmove ==

move mails between primary and alternative mailbox storage locations. Applicable to mdbox and sdbox mailbox formats only

parameters:

<nowiki>
{
"command": "altmove",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "reverse",
"type": "boolean"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to apply move
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|reverse
|Boolean
|search query to apply to mail move
|
|-
|query
|String array
|search query to apply to mail move
|
|}

example:

<nowiki>
[
[
"altmove",
{
"query": [
"mailbox",
"INBOX/myfoldertoo",
"savedbefore",
"since",
"30d"
],
"reverse": 0,
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["altmove",{"user":"samik","reverse":0,"query":["mailbox","INBOX/myfoldertoo","savedbefore","since","30d"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

== doveadm deduplicate ==

This command is used to expunge duplicated messages in mailboxes

parameters:

<nowiki>
{
"command": "deduplicate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "byMsgid",
"type": "boolean"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to deduplicate
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|byMsgId
|Boolean
|deduplicate by Message-ID instead of guid
|
|-
|query
|String array
|search query to apply to deduplicate
|
|}

== doveadm expunge ==

Expunge messages matching given search query

parameters:

<nowiki>
{
"command": "expunge",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "deleteEmptyMailbox",
"type": "boolean"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to expunge
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|deleteEmptyMailbox
|Boolean
|delete also mailbox if it’s empty after expunge has been applied
|
|-
|query
|String array
|search query to apply to expunge
|
|}

== doveadm flags ==
add, remove or replace messages' flags

=== doveadm flags add ===

add flag to a message or messages

parameters:

<nowiki>
{
"command": "flagsAdd",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "flag",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to add flags
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|flag
|String array
|list of flags to add
|
|-
|query
|String array
|search query to apply to flag add
|
|}

=== doveadm flags remove ===

remove flags from message or messages

parameters:

<nowiki>
{
"command": "flagsRemove",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "flag",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to add flags
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|flag
|String array
|list of flags to remove
|
|-
|query
|String array
|search query to apply to flag remove
|
|}

=== doveadm flags replace ===

Replace flags with another flag in message or messages. Replaces all current flags with the ones in the parameter list

parameters:

<nowiki>
{
"command": "flagsReplace",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "flag",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to replace flags
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|flag
|String array
|list of flags to replace with
|
|-
|query
|String array
|search query to apply to flag replace
|
|}

== doveadm import ==

Import messages matching given search query

parameters:

<nowiki>
{
"command": "import",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "subscribe",
"type": "boolean"
},
{
"name": "sourceLocation",
"type": "string"
},
{
"name": "destParentMailbox",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to apply import
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|subscribe
|boolean
|when enabled possible newly created folders are also subscibed
|
|-
|sourceLocation
|String
|location of source mailboxes
|
|-
|destParentMailbox
|String
|destination parent mailbox where to import
|
|-
|query
|String array
|search query for messages to import
|
|}

== doveadm force-resync ==

Under certain circumstances it may happen, that dovecot is unable to automatically solve problems with mailboxes. In such situations the force-resync command may be helpful. It tries to fix all problems. For sdbox and mdbox mailboxes the storage files will be also checked.

parameters:

<nowiki>
{
"command": "forceResync",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailboxMask",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|user
|String
|uid of user to apply resync
|
|-
|mailboxMask
|String
|apply forced resync on given mailboxes
|INBOX*
|}

example:

<nowiki>
[
[
"forceResync",
{
"mailboxMask": "INBOX*",
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["forceResync",{"user":"samik","mailboxMask":"INBOX*"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm force-resync –u samik “INBOX*”
</nowiki>

== doveadm purge ==

Remove messages with refcount=0 from mdbox files

parameters:

<nowiki>
{
"command": "purge",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to apply purge
|
|}

== doveadm search ==

Show a list of mailbox GUIDs and message UIDs matching given search query

parameters:

<nowiki>
{
"command": "search",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|user
|String
|uid of user to apply purge
|
|-
|query
|String array
|search query
|
|}

example:

<nowiki>
[
[
"search",
{
"query": [
"mailbox",
"INBOX*",
"all"
],
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["search",{"user":"samik","query":["mailbox","INBOX*","all"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"mailbox-guid": "cf497f128caf7c58612200007afd792c",
"uid": "1"
}
],
"bb"
]
]

CLI: doveadm search –u samik mailbox “INBOX*” all
</nowiki>

== doveadm copy ==

Copy messages matching the given search query into another mailbox

parameters:

<nowiki>
{
"command": "copy",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "destinationMailbox",
"type": "string"
},
{
"name": "sourceType",
"type": "string"
},
{
"name": "sourceUser",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm move ==

Move messages matching the given search query into another mailbox

parameters:

<nowiki>
{
"command": "move",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "destinationMailbox",
"type": "string"
},
{
"name": "sourceType",
"type": "string"
},
{
"name": "sourceUser",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm fscache rescan ==

force fscache rescan

parameters:

<nowiki>
{
"command": "fscacheRescan",
"parameters": [
{
"name": "path",
"type": "string"
},
{
"name": "maxAge",
"type": "integer"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm metacache ==
=== doveadm metacache clean ===

clean metacache content for given user or all users

parameters:

<nowiki>
{

"command": "metacacheClean",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "days",
"type": "integer"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache flush ===

flush metacache contents to storage for given user or all users

parameters:

<nowiki>
{
"command": "metacacheFlush",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache unpack ===

unpack metacache index bundle to target directory

parameters:

<nowiki>
{
"command": "metacacheUnpack",
"parameters": [
{
"name": "bundleName",
"type": "string"
},
{
"name": "bundle",
"type": "string"
},
{
"name": "destinationDirectory",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache flushall ===

flush metacache to storage for all users

parameters:

<nowiki>
{
"command": "metacacheFlushall",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache remove ===

remove metacache for given mask

parameters:

<nowiki>
{
"command": "metacacheRemove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "mask",
"type": "string"
}
]
}
</nowiki>
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache list ===

list local metacache contents

parameters:

<nowiki>
{
"command": "metacacheList",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm obox user delete ==

delete user data from storage, Cassandra and local caches (metacache and fscache).

parameters:

<nowiki>
{
"command": "oboxUserDelete",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

example:

<nowiki>
[
[
"oboxUserDelete",
{
"allUsers": 0,
"socketPath": "",
"user": "testuser003",
"userFile": ""
},
"aa"
]
]

# curl -v -u doveadm:hellodoveadm -X POST http://localhost:ype: application/json" -d '[["oboxUserDelete", {"allUsers":0,"user":"testuser003"}, "aa"]]'
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"aa"
]
]

CLI: doveadm obox user delete –u testuser003
</nowiki>

== doveadm sieve ==

Commands related to handling Sieve scripts.

=== doveadm sieve list ===

list user sieve scripts

parameters:

<nowiki>
{
"command": "sieveList",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve get ===

get user sieve script

parameters:

<nowiki>
{
"command": "sieveGet",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "scriptname",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve put ===

inject sieve script to user

parameters:

<nowiki>
{
"command": "sievePut",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "activate",
"type": "boolean"
},
{
"name": "scriptname",
"type": "string"
},
{
"name": "file",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve delete ===

delete user sieve

parameters:

<nowiki>
{
"command": "sieveDelete",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "ignoreActive",
"type": "boolean"
},
{
"name": "scriptname",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve activate ===

activate user sieve script

parameters:

<nowiki>
{
"command": "sieveActivate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "scriptname",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve deactivate ===

deactivate user sieve

parameters:

<nowiki>
{
"command": "sieveDeactivate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve rename ===

rename user sieve script

parameters:

<nowiki>
{
"command": "sieveRename",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "oldname",
"type": "string"
},
{
"name": "newname",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm fts ==
Dovecot fts indexing commands.

=== doveadm fts lookup ===

query user fts indexed data

parameters:

<nowiki>
{
"command": "ftsLookup",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts expand ===

<nowiki>
{
"command": "ftsExpand",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts tokenize ===

<nowiki>
{
"command": "ftsTokenize",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "language",
"type": "string"
},
{
"name": "text",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts optimize ===

<nowiki>
{
"command": "ftsOptimize",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts rescan ===

<nowiki>
{
"command": "ftsRescan",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

Template:DoveadmHTTPapi

2017-03-15T12:29:36Z

Oskarikentta: /* doveadm mailbox list */

== Table of Contents ==
__TOC__

== 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:

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

=== 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:

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

Basic auth usage:
<nowiki>
curl -H "Authorization: Basic <base64 doveadm:doveadm_password>"
http://host:port/doveadm/v1
</nowiki>
or by letting curl to form the base64 encoded authentication basig authentication header:

<nowiki>
curl –u doveadm:password http://host:port/doveadm/v1
</nowiki>

=== 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:

<nowiki>

[
[
"command1",
{
"parameter1": "value",
"parameter2": "value",
"parameter3": "value"
},
"identifier"
]
]
</nowiki>
Multiple commands can be submitted in one json payload:
<nowiki>
[
[
"command1",
{
"parameter1": "value",
"parameter2": "value"
},
"identifier1"
],
[
"command2",
{
"parameter1": "value",
"parameter2": "value"
},
"identifier2"
]
]
</nowiki>

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:

<nowiki>

son payload:

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

</nowiki>

submitting the command with curl:

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

command line equivalent

doveadm reload

=== successful response ===

<nowiki>

[
[
"doveadmResponse",
[],
"a2"
]
]
</nowiki>

=== failure response ===

<nowiki>

[
[
"error",
{
"exitCode": 68,
"type": "exitCode"
},
"a2"
]
</nowiki>

=== failure codes ===

{| class="wikitable"
|-
|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
|}

== Supported commands ==

== doveadm service ==
=== doveadm service stop ===

stop one or more dovecot services on target host

<nowiki>
{
"command": "serviceStop",
"parameters": [
{
"name": "service",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|service
|string array
|Name of service to stop
|[“imap”,”imap-hibernate”]
|}

example:

<nowiki>
[
[
"serviceStop",
{
"service": [
"imap",
"imap-hibernate"
]
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["serviceStop",{"service":["imap","imap-hibernate"]},"aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm service stop imap imap-hibernate
</nowiki>

=== doveadm stop ===

stop dovecot on the target host
<nowiki>

{
"command": "stop",
"parameters": []
}

no parameters
</nowiki>
example:
<nowiki>
[
[
"stop",
{},
"a1"
]
]

# curl -u doveadm:hellodoveadm -X POST http://localhost:8080/doveadm/v1 -H "Content-Type: application/json" -d '[["stop",{},"a1"]]'

CLI: doveadm stop
</nowiki>

=== doveadm reload ===

reload dovecot configuration

<nowiki>
{
"command": "reload",
"parameters": []
}
</nowiki>

example:

<nowiki>
[
[
"reload",
{},
"a2"
]
]

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

CLI: doveadm reload
</nowiki>

== doveadm stats ==
=== doveadm stats dump ===

dump collected dovecot statistics

<nowiki>
{
"command": "statsDump",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "type",
"type": "string"
},
{
"name": "filter",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|+parameters
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|type
|String
|Type of stats to dump
|global
|-
|filter
|String
|Dump filter
|last_update 1483101542
|}

Example:

<nowiki>
[
[
"statsDump",
{
"type": "global"
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["statsDump",{"type":"global"},"aa"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"auth_cache_hits": "0",
"auth_cache_misses": "0",
"auth_db_tempfails": "0",
"auth_failures": "0",
"auth_master_successes": "0",
"auth_successes": "0",
"clock_time": "0.0",
"disk_input": "0",
"disk_output": "0",
"fscache_read": "0",
"fscache_stat": "0",
"fscache_write": "0",
"idx_del": "0",
"idx_iter": "0",
"idx_read": "0",
"idx_read_usecs": "0",
"idx_wbytes": "0",
"idx_write": "0",
"idx_write_usecs": "0",
"invol_cs": "0",
"last_update": "0.000000",
"mail_cache_hits": "0",
"mail_lookup_attr": "0",
"mail_lookup_path": "0",
"mail_read_bytes": "0",
"mail_read_count": "0",
"maj_faults": "0",
"min_faults": "0",
"num_cmds": "0",
"num_connected_sessions": "0",
"num_logins": "0",
"obox_copy": "0",
"obox_del": "0",
"obox_iter": "0",
"obox_read": "0",
"obox_read_usecs": "0",
"obox_stat": "0",
"obox_wbytes": "0",
"obox_write": "0",
"obox_write_usecs": "0",
"read_bytes": "0",
"read_count": "0",
"reset_timestamp": "1483104199",
"sys_cpu": "0.0",
"user_cpu": "0.0",
"vol_cs": "0",
"write_bytes": "0",
"write_count": "0"
}
],
"aa"
]
]

CLI: doveadm stats dump global
</nowiki>

=== doveadm stats reset ===
reset dovecot statistics counters
<nowiki>

{
"command": "statsReset",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|}

example:

<nowiki>
[
[
"statsReset",
{},
"aa"
]
]

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

CLI: doveadm stats reset
</nowiki>

== doveadm penalty ==

<nowiki>
show current penalties

{
"command": "penalty",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "netmask",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|string
|Path to doveadm socket
|/var/run/dovecot-server
|-
|netmask
|string
|To reduce/filter the output supply an IP address or a network range in CIDR notation (ip/mask)
|10.0.0.0/24
|}

example:

<nowiki>
[
[
"penalty",
{},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["penalty",{},"aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm penalty
</nowiki>

== doveadm kick ==

Kick user from dovecot. Applicable to session in dovecot backend only

<nowiki>
{
"command": "kick",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "force",
"type": "boolean"
},
{
"name": "mask",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|force
|Boolean
|Do a forced kick?
|0
|-
|mask
|String
|Uid mask
|testuser001
|}

example:

<nowiki>
[
[
"kick",
{
"force": 0,
"mask": "testuser001"
},
"aa"
]
]

# curl -v -u doveadm:hellodoveadm –H “Content-Type: application/json" -d '[["kick", {"mask":"testuser001"}, "aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm kick testuser001
</nowiki>

response for succesfull kick:

<nowiki>
[
[
"doveadmResponse",
[
{
"result": "testuser001"
}
],
"aa"
]
]
</nowiki>

response in case kick failed:

<nowiki>
[
[
"error",
{
"exitCode": 68,
"type": "exitCode"
},
"aa"
]
]
</nowiki>

== doveadm who ==

<nowiki>
list active dovecot sessions

{
"command": "who",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "separateConnections",
"type": "boolean"
},
{
"name": "mask",
"type": "array"
}
]
}
</nowiki>

parameters

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|string
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|separateConnections
|Boolean
|Show each user connection in separate entries
|0
|-
|mask
|string array
|Uid mask
|testuser001
|}

Example:

<nowiki>
[
[
"who",
{
"mask": "",
"separateConnections": 0,
"socketPath": ""
},
"aa"
]
]

# curl -v -u doveadm:hellodoveadm -X POST http://localhost:ype: application/json" -d '[["who", {}, "aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm who
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"connections": "1",
"ips": "(127.0.0.1)",
"pids": "(4999)",
"service": "imap",
"username": "testuser001"
}
],
"aa"
]
]
</nowiki>

== doveadm director ==
=== doveadm director status ===

Show backend statuses on directors. Available only in directors

<nowiki>
[
{
"command": "directorStatus",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "tag",
"type": "string"
}
]
}
]
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|String
|Show director status for Tagged hosts only
|NewBackend
|}

example:

<nowiki>
[
[
"directorStatus",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorStatus",{},"bb"]]' http://localhost:8080/doveadm/v1

</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"mail server ip": "10.0.0.234",
"state": "up",
"state-changed": "2016-12-15 08:31:37",
"tag": "",
"users": "1",
"vhosts": "100"
},
{
"mail server ip": "10.0.0.235",
"state": "up",
"state-changed": "2016-12-15 08:31:04",
"tag": "",
"users": "0",
"vhosts": "100"
}
],
"bb"
]
]

CLI: doveadm director status
</nowiki>

=== doveadm director map ===

list current user → host mappings. Applicable to director only

<nowiki>

"command": "directorMap",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "usersFile",
"type": "string"
},
{
"name": "hashMap",
"type": "boolean"
},
{
"name": "userMap",
"type": "boolean"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

parameters

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|usersFile
|String
|provide Path to users list. One username per line
|/etc/dovecot/userlist.txt
|-
|hashMap
|Boolean
|Output users as hashmap
|True
|-
|userMap
|Boolean
|Output users as userlist
|True
|-
|host
|String
|Show only mappings to given host
|10.0.0.234
|}

example:

<nowiki>
[
[
"directorMap",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorMap",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"expire time": "2016-12-30 14:52:56",
"hash": "3853430566",
"mail server ip": "10.0.0.235",
"user": "samik"
}
],
"bb"
]
]

CLI: doveadm director map
</nowiki>

=== doveadm director add ===

add backend to director ring

<nowiki>
{
"command": "directorAdd",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "tag",
"type": "string"
},
{
"name": "host",
"type": "string"
},
{
"name": "vhostCount",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|tag
|String
|apply tag to backend
|/etc/dovecot/userlist.txt
|-
|host
|String
|backend ip to add
|10.0.0.234
|-
|vhostCount
|String
|vhost count to add
|100
|}

Example:

<nowiki>
[
[
"directorAdd",
{
"host": "10.0.234"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorAdd",{"host":"10.0.234"},"bb"]]' http://localhost:8080/doveadm/v1

CLI: doveadm director add 10.0.0.234
</nowiki>

=== doveadm director update ===

<nowiki>
{
"command": "directorUpdate",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
},
{
"name": "vhostCount",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|string
|Show director status for tagged hosts only
|NewBackend
|}

=== doveadm director up ===

<nowiki>
{
"command": "directorUp",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|string
|Show director status for tagged hosts only
|NewBackend
|}

=== doveadm director down ===

<nowiki>
{
"command": "directorDown",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|string
|Show director status for tagged hosts only
|NewBackend
|}

=== doveadm director remove ===

remove backend from director ring

<nowiki>
{
"command": "directorRemove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|host
|String
|backend to remove
|10.0.0.134
|}

example:

<nowiki>
[
[
"directorRemove",
{
"host": "10.0.0.234"
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRemove",{"host":"10.0.0.234"},"aa"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"aa"
]
]

CLI: doveadm director remove 10.0.0.234
</nowiki>

=== doveadm director move ===

move user mapping from backend to another or create director mapping for an user
<nowiki>
{
"command": "directorMove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|user
|String
|User uid to move
|testuser001
|-
|host
|string
|Target backend ip as listed in doveadm doveadm director status
|10.0.0.234
|}

example:

<nowiki>
[
[
"directorMove",
{
"host": "10.0.234",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorMove",{"user":"samik","host":"10.0.234"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director move samik 10.0.0.234
</nowiki>

== doveadm director kick ==

<nowiki>
{
"command": "directorKick",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|user
|String
|uid of user to kick
|samik
|}

example:

<nowiki>
[
[
"directorKick",
{
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorKick",{"user":"samik"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director kick samik
</nowiki>

=== doveadm director flush ===

flush connection mappings to one backend at director level. All users mapped to given host will be flushed from the hashmap table and will be redistributed to backends.

Parameters:

<nowiki>
{
"command": "directorFlush",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "forceFlush",
"type": "boolean"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|forceFlush
|Boolean
|Flag to make flush forced
|True
|-
|host
|String
|Backend ip address from doveadm director status list
|10.0.0.234
|}

example:

<nowiki>
[
[
"directorFlush",
{
"host": "10.0.0.234"
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorFlush",{"host":"10.0.0.234"},"aa"]]' http://localhost:8080/doveadm/v1

</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"aa"
]
]
CLI: doveadm director flush 10.0.234
</nowiki>

=== doveadm director dump ===

Dumb the current director backend host configuration as commands

<nowiki>
{
"command": "directorDump",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|}

example:

<nowiki>
[
[
"directorDump",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorDump",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"command": "add",
"host": "10.0.0.234",
"socket-path": "/var/run/dovecot/director-admin",
"vhost_count": "100"
},
{
"command": "add",
"host": "10.0.0.235",
"socket-path": "/var/run/dovecot/director-admin",
"vhost_count": "100"
}
],
"bb"
]
]

CLI: doveadm director dump
</nowiki>

=== doveadm director ring add ===

add new director to director ring

parameters:

<nowiki>
{
"command": "directorRingAdd",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "ip",
"type": "string"
},
{
"name": "port",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|ip
|String
|director ip address to add
|10.0.0.233
|-
|port
|String
|port number to use if not default
|9143
|}

example:

<nowiki>
[
[
"directorRingAdd",
{
"ip": "10.0.0.233"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRingAdd",{"ip":"10.0.0.233"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director ring add 10.0.0.233
</nowiki>

=== doveadm director ring remove ===

remove director from director ring

parameters:

<nowiki>
{
"command": "directorRingRemove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "ip",
"type": "string"
},
{
"name": "port",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|ip
|String
|director ip to remove
|10.0.0.233
|-
|port
|String
|director service port if not default
|9143
|}

example:

<nowiki>
[
[
"directorRingRemove",
{
"ip": "10.0.0.233"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRingRemove",{"ip":"10.0.0.233"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director ring remove 10.0.0.233
</nowiki>

=== doveadm director ring status ===

show director ring status

parameters:

<nowiki>

{
"command": "directorRingStatus",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|}

example:

<nowiki>
[
[
"directorRingStatus",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRingStatus",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>

[
"doveadmResponse",
[
{
"director ip": "10.0.0.232",
"last failed": "never",
"port": "9143",
"status": "synced",
"type": "self"
},
{
"director ip": "10.0.0.233",
"last failed": "never",
"port": "9143",
"status": "",
"type": ""
}
],
"bb"
]
]

CLI: doveadm director ring status
</nowiki>

== doveadm proxy ==

The doveadm proxy commands are used to list or kick active Dovecot proxy connections.

=== doveadm proxy list ===

list active connections in the dovecot proxy

parameters:

<nowiki>
{
"command": "proxyList",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|}

example:

<nowiki>
[
[
"proxyList",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["proxyList",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"dest-ip": "127.0.0.1",
"dest-port": "1143",
"service": "imap",
"src-ip": "10.0.0.153",
"username": "samik"
}
],
"bb"
]
]

CLI: doveadm proxy list
</nowiki>

=== doveadm proxy kick ===

kick user session from proxy. applicable to imap/pop3/managesieve sessions

parameters:

<nowiki>
{
"command": "proxyKick",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|userid to kick
|samik
|}

example:

<nowiki>
[
[
"proxyKick",
{
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["proxyKick",{"user":"samik"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"count": "1"
}
],
"bb"
]
]

CLI: doveadm proxy kick samik
</nowiki>

== doveadm logs errors ==

fetch errors log

paraments:

<nowiki>
{
"command": "logErrors",
"parameters": [
{
"name": "since",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|}

example:

<nowiki>
[
[
"logErrors",
{},
"a2"
]
]

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

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"prefix": "stats",
"text": "Stats client input error: Invalid level",
"timestamp": "Dec 09 16:24:00",
"type": "Error"
},
{
"prefix": "doveadm(127.0.0.1)",
"text": "read(/var/run/dovecot/stats) unexpectedly disconnected",
"timestamp": "Dec 09 16:24:00",
"type": "Fatal"
},
{
"prefix": "stats",
"text": "Stats client input error: Invalid level",
"timestamp": "Dec 09 16:24:22",
"type": "Error"
},
{
"prefix": "stats",
"text": "Stats client input error: Invalid level",
"timestamp": "Dec 09 16:27:48",
"type": "Error"
},
{
"prefix": "director",
"text": "Empty server list",
"timestamp": "Dec 09 16:29:13",
"type": "Error"
},
{
"prefix": "director",
"text": "Invalid value for director_mail_servers setting",
"timestamp": "Dec 09 16:29:13",
"type": "Fatal"
}
],
"a2"
]
]

CLI: doveadm log errors
</nowiki>

== doveadm dict ==
=== doveadm dict get ===

get user key value from configured dictionary

parameters:

<nowiki>
{
"command": "dictGet",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to query
|samik
|-
|dictUri
|String
|optional URI for dictionary to query
|
|-
|key
|String
|key to query
|
|}

=== doveadm dict set ===

set user key value in configured dictionary

parameters:

<nowiki>
{
"command": "dictSet",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
},
{
"name": "value",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|samik
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|key
|String
|dictionary key to modify
|
|-
|value
|string
|value to set
|
|}

=== doveadm dict unset ===

unset user key value in configured dictionary

parameters:

<nowiki>
{
"command": "dictUnset",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|key
|String
|dictionary key to unset
|
|}
== doveadm dict inc ==

increase users key value in dictionary

parameters:

<nowiki>
{
"command": "dictInc",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
},
{
"name": "difference",
"type": "integer"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|-
|key
|String
|dictionary key to increase
|
|-
|difference
|integer
|increment value
|
|}

=== doveadm dict iter ===

list user keys in dictionary

parameters:

<nowiki>
{
"command": "dictIter",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "exact",
"type": "boolean"
},
{
"name": "recurse",
"type": "boolean"
},
{
"name": "noValue",
"type": "boolean"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "prefix",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|exact
|Boolean
|list only exact matches
|
|-
|recurce
|Boolean
|do recursive search
|
|-
|noValue
|Boolean
|list also keys that have no value set
|
|-
|prefix
|String
|search only keys with given prefix
|
|}

== doveadm fs ==
=== doveadm fs get ===

get object from storage

parameters:

<nowiki>
{
"command": "fsGet",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem to fetch
|
|}

=== doveadm fs put ===

put object to storage

parameters:

<nowiki>
{
"command": "fsPut",
"parameters": [
{
"name": "hash",
"type": "string"
},
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "inputPath",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|hash
|string
|
|
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|inputPath
|String
|source object path in local filesystem
|
|-
|path
|String
|object path filesystem to put
|
|}

=== doveadm fs copy ===

copy object in storage

parameters:

<nowiki>
{
"command": "fsCopy",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "sourcePath",
"type": "string"
},
{
"name": "destinationPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|sourcePath
|String
|source object path
|
|-
|Destination path
|String
|destination object path in filesystem
|
|}

=== doveadm fs stat ===

fetch fs driver statistics

parameters:

<nowiki>
{
"command": "fsStat",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem fetch statistics for
|
|}

=== doveadm fs metadata ===

get filesystem object metadata

parameters:

<nowiki>
{
"command": "fsMetadata",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem fetch metadata for
|
|}

=== doveadm fs delete ===

delete object from storage

<nowiki>
{
"command": "fsDelete",
"parameters": [
{
"name": "recursive",
"type": "boolean"
},
{
"name": "maxParallel",
"type": "integer"
},
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem to delete
|
|-
|recursive
|Boolean
|do a recursive delete of path
|
|-
|maxParallel
|integer
|max number of parallel workers
|
|}

=== doveadm fs iter ===

list objects in given fs path

parameters:

<nowiki>
{
"command": "fsIter",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|path in filesystem to list
|
|}

=== doveadm fs iter-dirs ===
ist subfolders in given path

parameters:

<nowiki>
{
"command": "fsIterDirs",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|path in filesystem to list for subfolders
|
|}

== doveadm auth cache flush ==

flush authentication cache for one user or all users

parameters:

<nowiki>
{
"command": "authCacheFlush",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String array
|optional list of users in flush
|[“samik”,”samitest”]
|}

example:

<nowiki>
[
[
"authCacheFlush",
{
"user": [
"samik"
]
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["authCacheFlush",{"user":["samik"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"entries": "0"
}
],
"bb"
]
]

CLI: doveadm auth cache flush samik
</nowiki>

== doveadm user ==

do a userdb lookup for an user

<nowiki>
{
"command": "user",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "authInfo",
"type": "array"
},
{
"name": "field",
"type": "string"
},
{
"name": "expandField",
"type": "string"
},
{
"name": "userdbOnly",
"type": "boolean"
},
{
"name": "userMask",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|authInfo
|String array
|auth_info specifies additional conditions for the user command. The auth_info option string has to be given as name=value pair. For multiple conditions the -x option could be supplied multiple times.
Possible names for the auth_info are:
service
The service for which the userdb lookup should be tested. The value may be the name of a service, commonly used with Dovecot. For example: imap, pop3 or smtp.
lip
The local IP address (server) for the test.
rip
The remote IP address (client) for the test.
lport
The local port, e.g. 143
rport
The remote port, e.g. 24567
|sevice=imap
|-
|field
|String
|fetch only one specified field instead of all
|
|-
|expandField
|String
|expand configuration variable with user specific values
|
|-
|userdbOnly
|Boolean
|only fetch from userdb lookup and don’t process passdb
|
|-
|userMask
|String array
|search filter
|
|}

example:

<nowiki>
[
[
"user",
{
"userMask": [
"samik"
]
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["user",{"userMask":["samik"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
{
"samik": {
"gid": "1000",
"home": "/var/vmail/samik",
"junkflag": "0",
"mail": "Maildir:/mails/mails/samik/Maildir",
"namespace/Junk/hidden": "no",
"namespace/Junk/list": "yes",
"uid": "1000"
}
},
"bb"
]
]

CLI: doveadm user samik
</nowiki>

== doveadm mailbox ==
=== doveadm mailbox metadata set ===

set user mailbox metadata

parameters:

<nowiki>
{
"command": "mailboxMetadataSet",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "key",
"type": "string"
},
{
"name": "value",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata set
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to set
|
|-
|value
|String
|metadata value to set
|
|}

example:

<nowiki>
[
[
"mailboxMetadataSet",
{
"key": "/private/comment",
"mailbox": "INBOX",
"user": "samik",
"value": "test"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataSet",{"user":"samik","mailbox":"INBOX","key":"/private/comment","value":"test"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox metadata set –u samik INBOX /private/comment test
</nowiki>

=== doveadm mailbox metadata unset ===

unset user mailbox metadata

parameters:

<nowiki>
{
"command": "mailboxMetadataUnset",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata unset
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to unset
|
|}

example:

<nowiki>
[
[
"mailboxMetadataUnset",
{
"key": "/private/comment",
"mailbox": "INBOX",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataUnset",{"user":"samik","mailbox":"INBOX","key":"/private/comment"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox metadata unset –u samik INBOX /private/comment
</nowiki>

=== doveadm mailbox metadata get ===

get user mailbox metadata

parameters:

<nowiki>
{
"command": "mailboxMetadataGet",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata get
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to get
|
|}

example:

<nowiki>
[
[
"mailboxMetadataGet",
{
"key": "/private/comment",
"mailbox": "INBOX",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataGet",{"user":"samik","mailbox":"INBOX","key":"/private/comment"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response

<nowiki>
[
[
"doveadmResponse",
[
{
"value": "plaa"
}
],
"bb"
]
]

CLI: doveadm mailbox metadata get –u samik INBOX /private/comment
</nowiki>

=== doveadm mailbox list ===

list user mailbox metadata for a folder

parameters:

<nowiki>

"command": "mailboxMetadataList",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "keyPrefix",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata get
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to get
|
|-
|keyPrefix
|String
|search prefix for keys
|
|-
|mailbox
|String
|mailbox to fetch metadata from
|
|}

example:

<nowiki>
[
[
"mailboxMetadataList",
{
"mailbox": "INBOX",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataList",{"user":"samik","mailbox":"INBOX"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"key": "comment"
},
{
"key": "specialuse"
}
],
"bb"
]
]

CLI: doveadm mailbox metadata list –u samik INBOX
</nowiki>

=== doveadm mailbox status ===

fetch user mailbox status

parameters:

<nowiki>
{
"command": "mailboxStatus",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "totalSum",
"type": "boolean"
},
{
"name": "field",
"type": "array"
},
{
"name": "mailboxMask",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply status fetch
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|totalSum
|boolean
|
|
|-
|field
|String array
|fields to fetch
|all
|-
|mailboxMask
|String array
|fetch status on given mailboxes
|
|}

example:

<nowiki>

[
[
"mailboxStatus",
{
"field": [
"all"
],
"mailboxMask": [
"INBOX",
"INBOX/*",
"*"
],
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxStatus",{"user":"samik","field":["all"],"mailboxMask":["INBOX","INBOX/*","*"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"guid": "21b588150b156558eb3500007afd792c",
"highestmodseq": "5",
"mailbox": "Junk",
"messages": "0",
"recent": "0",
"uidnext": "1",
"uidvalidity": "1483019529",
"unseen": "0",
"vsize": "0"
},
{
"guid": "21b588150b156558eb3500007afd792c",
"highestmodseq": "5",
"mailbox": "INBOX",
"messages": "0",
"recent": "0",
"uidnext": "1",
"uidvalidity": "1483019529",
"unseen": "0",
"vsize": "0"
}
],
"bb"
]
]

CLI: doveadm mailbox status –u samik all “*”
</nowiki>

=== doveadm mailbox list ===

fetch user folder list

parameters:

<nowiki>
{
"command": "mailboxList",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mutf7",
"type": "boolean"
},
{
"name": "utf8",
"type": "boolean"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "mailboxMask",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply mailbox list
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|mutf7
|Boolean
|
|
|-
|utf8
|Boolean
|fetch only certain fields instead of all
|
|-
|subscription
|Boolean
|
|
|-
|mailboxMask
|String array
|fetch list of given mailboxes
|
|}

example:

<nowiki>
[
[
"mailboxList",
{
"user": "samik"
},
"bb"
]
]
# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxList",{"user":"samik"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"mailbox": "Junk"
},
{
"mailbox": "INBOX"
}
],
"bb"
]
]

CLI: doveadm mailbox list –u samik
</nowiki>

=== doveadm mailbox create ===
create mailbox folder for user

parameters:

<nowiki>
{
"command": "mailboxCreate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "guid",
"type": "string"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply mailbox create
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|subscription
|Boolean
|
|
|-
|mailbox
|String array
|list of mailbox folders to create
|
|}

example:

<nowiki>
[
[
"mailboxCreate",
{
"mailbox": [
"INBOX/myfolder"
],
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxCreate",{"user":"samik","mailbox":["INBOX/myfolder"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>

[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox create –u samik INBOX/myfolder
</nowiki>

=== doveadm mailbox delete ===

delete user mailbox folder

parameters:

<nowiki>
{
"command": "mailboxDelete",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "requireEmpty",
"type": "boolean"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "recursive",
"type": "boolean"
},
{
"name": "unsafe",
"type": "boolean"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply delete
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|requireEmpty
|Boolean
|only delete if folder is empty
|
|-
|subscription
|Boolean
|
|
|-
|recursive
|Boolean
|delete also subfolders
|
|-
|unsafe
|Boolean
|
|
|-
|mailbox
|String array
|list of mailbox folders to create
|
|}

example:

<nowiki>
[
[
"mailboxDelete",
{
"mailbox": [
"INBOX/myfolder"
],
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxDelete",{"user":"samik","mailbox":["INBOX/myfolder"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox delete –u samik INBOX/myfolder
</nowiki>

=== doveadm mailbox rename ===

rename user folder

parameters:

<nowiki>
{
"command": "mailboxRename",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "newName",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply mailbox rename
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|subscriptions
|Boolean
|
|
|-
|newName
|String
|mailbox new name
|
|-
|mailbox
|String
|mailbox to rename
|
|}

example:

<nowiki>
[
[
"mailboxRename",
{
"mailbox": "INBOX/myfolder",
"newName": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxRename",{"user":"samik","mailbox":"INBOX/myfolder","newName":"INBOX/myfoldertoo"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox rename –u samik INBOX/myfolder INBOX/myfoldertoo
</nowiki>

=== doveadm mailbox subscribe ===

subscribe user to a mailbox

parameters:

<nowiki>
{
"command": "mailboxSubscribe",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply subscribe
|
|-
|userFile
|String
|optionally fetch usernames from. One username per line
|
|-
|mailbox
|String
|mailbox to subscribe
|
|}

example:

<nowiki>
[
[
"mailboxSubscribe",
{
"mailbox": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxSubscribe",{"user":"samik","mailbox":"INBOX/myfoldertoo"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:
<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox subscribe –u samik INBOX/myfoldertoo
</nowiki>

=== doveadm mailbox unsubscribe ===

unsubscribe user from an folder

parameters:

<nowiki>
{
"command": "mailboxUnsubscribe",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply unsubscribe
|
|-
|userFile
|String
|optionally fetch usernames from. One username per line
|
|-
|mailbox
|String
|mailbox to unsubscribe
|
|}

example:

<nowiki>
[
[
"mailboxUnsubscribe",
{
"mailbox": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxUnsubscribe",{"user":"samik","mailbox":"INBOX/myfoldertoo"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox unsubscribe –u samik INBOX/myfoldertoo
</nowiki>

=== doveadm mailbox update ===

update user mailbox information

parameters:

<nowiki>
{
"command": "mailboxUpdate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailboxGuid",
"type": "string"
},
{
"name": "uidValidity",
"type": "string"
},
{
"name": "minNextUid",
"type": "string"
},
{
"name": "minFirstRecentUid",
"type": "string"
},
{
"name": "minHighestModseq",
"type": "string"
},
{
"name": "minHighestPvtModseq",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply update
|
|-
|userFile
|String
|optionally fetch usernames from. One username per line
|
|-
|mailbox
|String
|mailbox to unsubscribe
|
|-
|mailboxGuid
|String
|set mailbox guid
|
|-
|uidValidity
|String
|set mailbox uidvalidity
|
|-
|minNextuid
|String
|set mailbox minimum next uid
|
|-
|minFirstRecentuid
|String
|set mailbox minimum recent uid
|
|-
|minHighestModseq
|String
|
|
|-
|minHighestPvtModseq
|String
|
|
|}

=== doveadm mailbox save ===

save mail into users mailbox

parameters:

<nowiki>
{
"command": "save",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "file",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to save mail into
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|mailbox
|String
|mailbox to unsubscribe
|
|-
|file
|String
|mail to inject
|
|}

example:

<nowiki>
[
[
"save",
{
"file": "From: Joulu Pukki <joulu.pukki@korvatunturi.fi>\nSubject: plaa\n\nmail body\n",
"mailbox": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["save",{"user":"samik","mailbox":"INBOX/myfoldertoo","file":"From: Joulu Pukki <joulu.pukki@korvatunturi.fi>\nSubject: plaa\n\nmail body\n"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]
</nowiki>

== doveadm fetch ==

fetch data from user mailbox

parameters:

<nowiki>
{
"command": "fetch",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "field",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to fetch data
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|field
|String array
|fields to fetch. Supported fields as of dovecot 2.2.26: hdr.<name> body.<section> binary.<section> user mailbox mailbox-guid seq uid guid flags modseq hdr body body.snippet text text.utf8 size.physical size.virtual date.received date.sent date.saved date.received.unixtime date.sent.unixtime date.saved.unixtime imap.envelope imap.body imap.bodystructure pop3.uidl pop3.order refcount storageid
|
|-
|query
|String array
|search query to user
|
|}

example:

<nowiki>
[
[
"fetch",
{
"field": [
"text"
],
"query": [
"mailbox",
"INBOX/myfoldertoo"
],
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["fetch",{"user":"samik","field":["text"],"query":["mailbox","INBOX/myfoldertoo"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"text": "From: Joulu Pukki <joulu.pukki@korvatunturi.fi>\nSubject: plaa\n\nmail body\n"
}
],
"bb"
]
]

CLI: doveadm fetch –u samik “text” mailbox INBOX/myfoldertoo
</nowiki>

== doveadm index ==

index user mailbox folder or folders

parameters:

<nowiki>
{
"command": "index",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "queue",
"type": "boolean"
},
{
"name": "maxRecent",
"type": "string"
},
{
"name": "mailboxMask",
"type": "string"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to index
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|query
|Boolean
|max number of recent mails to index
|
|-
|maxRecent
|String
|max number of recent mails to index
|
|-
|mailboxMask
|String
|mailbox search mask to apply indexing into
|
|}

example:

<nowiki>
[
[
"index",
{
"mailboxMask": "INBOX*",
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["index",{"user":"samik","mailboxMask":"INBOX*"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm index –u samik “INBOX*”
</nowiki>

== doveadm altmove ==

move mails between primary and alternative mailbox storage locations. Applicable to mdbox and sdbox mailbox formats only

parameters:

<nowiki>
{
"command": "altmove",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "reverse",
"type": "boolean"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to apply move
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|reverse
|Boolean
|search query to apply to mail move
|
|-
|query
|String array
|search query to apply to mail move
|
|}

example:

<nowiki>
[
[
"altmove",
{
"query": [
"mailbox",
"INBOX/myfoldertoo",
"savedbefore",
"since",
"30d"
],
"reverse": 0,
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["altmove",{"user":"samik","reverse":0,"query":["mailbox","INBOX/myfoldertoo","savedbefore","since","30d"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

== doveadm deduplicate ==

This command is used to expunge duplicated messages in mailboxes

parameters:

<nowiki>
{
"command": "deduplicate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "byMsgid",
"type": "boolean"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to deduplicate
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|byMsgId
|Boolean
|deduplicate by Message-ID instead of guid
|
|-
|query
|String array
|search query to apply to deduplicate
|
|}

== doveadm expunge ==

Expunge messages matching given search query

parameters:

<nowiki>
{
"command": "expunge",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "deleteEmptyMailbox",
"type": "boolean"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to expunge
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|deleteEmptyMailbox
|Boolean
|delete also mailbox if it’s empty after expunge has been applied
|
|-
|query
|String array
|search query to apply to expunge
|
|}

== doveadm flags ==
add, remove or replace messages' flags

=== doveadm flags add ===

add flag to a message or messages

parameters:

<nowiki>
{
"command": "flagsAdd",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "flag",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to add flags
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|flag
|String array
|list of flags to add
|
|-
|query
|String array
|search query to apply to flag add
|
|}

=== doveadm flags remove ===

remove flags from message or messages

parameters:

<nowiki>
{
"command": "flagsRemove",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "flag",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to add flags
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|flag
|String array
|list of flags to remove
|
|-
|query
|String array
|search query to apply to flag remove
|
|}

=== doveadm flags replace ===

Replace flags with another flag in message or messages. Replaces all current flags with the ones in the parameter list

parameters:

<nowiki>
{
"command": "flagsReplace",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "flag",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to replace flags
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|flag
|String array
|list of flags to replace with
|
|-
|query
|String array
|search query to apply to flag replace
|
|}

== doveadm import ==

Import messages matching given search query

parameters:

<nowiki>
{
"command": "import",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "subscribe",
"type": "boolean"
},
{
"name": "sourceLocation",
"type": "string"
},
{
"name": "destParentMailbox",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to apply import
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|subscribe
|boolean
|when enabled possible newly created folders are also subscibed
|
|-
|sourceLocation
|String
|location of source mailboxes
|
|-
|destParentMailbox
|String
|destination parent mailbox where to import
|
|-
|query
|String array
|search query for messages to import
|
|}

== doveadm force-resync ==

Under certain circumstances it may happen, that dovecot is unable to automatically solve problems with mailboxes. In such situations the force-resync command may be helpful. It tries to fix all problems. For sdbox and mdbox mailboxes the storage files will be also checked.

parameters:

<nowiki>
{
"command": "forceResync",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailboxMask",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|user
|String
|uid of user to apply resync
|
|-
|mailboxMask
|String
|apply forced resync on given mailboxes
|INBOX*
|}

example:

<nowiki>
[
[
"forceResync",
{
"mailboxMask": "INBOX*",
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["forceResync",{"user":"samik","mailboxMask":"INBOX*"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm force-resync –u samik “INBOX*”
</nowiki>

== doveadm purge ==

Remove messages with refcount=0 from mdbox files

parameters:

<nowiki>
{
"command": "purge",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to apply purge
|
|}

== doveadm search ==

Show a list of mailbox GUIDs and message UIDs matching given search query

parameters:

<nowiki>
{
"command": "search",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|user
|String
|uid of user to apply purge
|
|-
|query
|String array
|search query
|
|}

example:

<nowiki>
[
[
"search",
{
"query": [
"mailbox",
"INBOX*",
"all"
],
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["search",{"user":"samik","query":["mailbox","INBOX*","all"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"mailbox-guid": "cf497f128caf7c58612200007afd792c",
"uid": "1"
}
],
"bb"
]
]

CLI: doveadm search –u samik mailbox “INBOX*” all
</nowiki>

== doveadm copy ==

Copy messages matching the given search query into another mailbox

parameters:

<nowiki>
{
"command": "copy",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "destinationMailbox",
"type": "string"
},
{
"name": "sourceType",
"type": "string"
},
{
"name": "sourceUser",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm move ==

Move messages matching the given search query into another mailbox

parameters:

<nowiki>
{
"command": "move",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "destinationMailbox",
"type": "string"
},
{
"name": "sourceType",
"type": "string"
},
{
"name": "sourceUser",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm fscache rescan ==

force fscache rescan

parameters:

<nowiki>
{
"command": "fscacheRescan",
"parameters": [
{
"name": "path",
"type": "string"
},
{
"name": "maxAge",
"type": "integer"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm metacache ==
=== doveadm metacache clean ===

clean metacache content for given user or all users

parameters:

<nowiki>
{

"command": "metacacheClean",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "days",
"type": "integer"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache flush ===

flush metacache contents to storage for given user or all users

parameters:

<nowiki>
{
"command": "metacacheFlush",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache unpack ===

unpack metacache index bundle to target directory

parameters:

<nowiki>
{
"command": "metacacheUnpack",
"parameters": [
{
"name": "bundleName",
"type": "string"
},
{
"name": "bundle",
"type": "string"
},
{
"name": "destinationDirectory",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache flushall ===

flush metacache to storage for all users

parameters:

<nowiki>
{
"command": "metacacheFlushall",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache remove ===

remove metacache for given mask

parameters:

<nowiki>
{
"command": "metacacheRemove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "mask",
"type": "string"
}
]
}
</nowiki>
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache list ===

list local metacache contents

parameters:

<nowiki>
{
"command": "metacacheList",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm obox user delete ==

delete user data from storage, Cassandra and local caches (metacache and fscache).

parameters:

<nowiki>
{
"command": "oboxUserDelete",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

example:

<nowiki>
[
[
"oboxUserDelete",
{
"allUsers": 0,
"socketPath": "",
"user": "testuser003",
"userFile": ""
},
"aa"
]
]

# curl -v -u doveadm:hellodoveadm -X POST http://localhost:ype: application/json" -d '[["oboxUserDelete", {"allUsers":0,"user":"testuser003"}, "aa"]]'
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"aa"
]
]

CLI: doveadm obox user delete –u testuser003
</nowiki>

== doveadm sieve ==

Commands related to handling Sieve scripts.

=== doveadm sieve list ===

list user sieve scripts

parameters:

<nowiki>
{
"command": "sieveList",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve get ===

get user sieve script

parameters:

<nowiki>
{
"command": "sieveGet",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "scriptname",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve put ===

inject sieve script to user

parameters:

<nowiki>
{
"command": "sievePut",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "activate",
"type": "boolean"
},
{
"name": "scriptname",
"type": "string"
},
{
"name": "file",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve delete ===

delete user sieve

parameters:

<nowiki>
{
"command": "sieveDelete",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "ignoreActive",
"type": "boolean"
},
{
"name": "scriptname",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve activate ===

activate user sieve script

parameters:

<nowiki>
{
"command": "sieveActivate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "scriptname",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve deactivate ===

deactivate user sieve

parameters:

<nowiki>
{
"command": "sieveDeactivate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve rename ===

rename user sieve script

parameters:

<nowiki>
{
"command": "sieveRename",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "oldname",
"type": "string"
},
{
"name": "newname",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm fts ==
Dovecot fts indexing commands.

=== doveadm fts lookup ===

query user fts indexed data

parameters:

<nowiki>
{
"command": "ftsLookup",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts expand ===

<nowiki>
{
"command": "ftsExpand",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts tokenize ===

<nowiki>
{
"command": "ftsTokenize",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "language",
"type": "string"
},
{
"name": "text",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts optimize ===

<nowiki>
{
"command": "ftsOptimize",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts rescan ===

<nowiki>
{
"command": "ftsRescan",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

Template:DoveadmHTTPapi

2017-03-15T12:20:24Z

Oskarikentta: /* doveadm fs delete */

== Table of Contents ==
__TOC__

== 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:

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

=== 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:

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

Basic auth usage:
<nowiki>
curl -H "Authorization: Basic <base64 doveadm:doveadm_password>"
http://host:port/doveadm/v1
</nowiki>
or by letting curl to form the base64 encoded authentication basig authentication header:

<nowiki>
curl –u doveadm:password http://host:port/doveadm/v1
</nowiki>

=== 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:

<nowiki>

[
[
"command1",
{
"parameter1": "value",
"parameter2": "value",
"parameter3": "value"
},
"identifier"
]
]
</nowiki>
Multiple commands can be submitted in one json payload:
<nowiki>
[
[
"command1",
{
"parameter1": "value",
"parameter2": "value"
},
"identifier1"
],
[
"command2",
{
"parameter1": "value",
"parameter2": "value"
},
"identifier2"
]
]
</nowiki>

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:

<nowiki>

son payload:

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

</nowiki>

submitting the command with curl:

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

command line equivalent

doveadm reload

=== successful response ===

<nowiki>

[
[
"doveadmResponse",
[],
"a2"
]
]
</nowiki>

=== failure response ===

<nowiki>

[
[
"error",
{
"exitCode": 68,
"type": "exitCode"
},
"a2"
]
</nowiki>

=== failure codes ===

{| class="wikitable"
|-
|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
|}

== Supported commands ==

== doveadm service ==
=== doveadm service stop ===

stop one or more dovecot services on target host

<nowiki>
{
"command": "serviceStop",
"parameters": [
{
"name": "service",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|service
|string array
|Name of service to stop
|[“imap”,”imap-hibernate”]
|}

example:

<nowiki>
[
[
"serviceStop",
{
"service": [
"imap",
"imap-hibernate"
]
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["serviceStop",{"service":["imap","imap-hibernate"]},"aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm service stop imap imap-hibernate
</nowiki>

=== doveadm stop ===

stop dovecot on the target host
<nowiki>

{
"command": "stop",
"parameters": []
}

no parameters
</nowiki>
example:
<nowiki>
[
[
"stop",
{},
"a1"
]
]

# curl -u doveadm:hellodoveadm -X POST http://localhost:8080/doveadm/v1 -H "Content-Type: application/json" -d '[["stop",{},"a1"]]'

CLI: doveadm stop
</nowiki>

=== doveadm reload ===

reload dovecot configuration

<nowiki>
{
"command": "reload",
"parameters": []
}
</nowiki>

example:

<nowiki>
[
[
"reload",
{},
"a2"
]
]

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

CLI: doveadm reload
</nowiki>

== doveadm stats ==
=== doveadm stats dump ===

dump collected dovecot statistics

<nowiki>
{
"command": "statsDump",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "type",
"type": "string"
},
{
"name": "filter",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|+parameters
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|type
|String
|Type of stats to dump
|global
|-
|filter
|String
|Dump filter
|last_update 1483101542
|}

Example:

<nowiki>
[
[
"statsDump",
{
"type": "global"
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["statsDump",{"type":"global"},"aa"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"auth_cache_hits": "0",
"auth_cache_misses": "0",
"auth_db_tempfails": "0",
"auth_failures": "0",
"auth_master_successes": "0",
"auth_successes": "0",
"clock_time": "0.0",
"disk_input": "0",
"disk_output": "0",
"fscache_read": "0",
"fscache_stat": "0",
"fscache_write": "0",
"idx_del": "0",
"idx_iter": "0",
"idx_read": "0",
"idx_read_usecs": "0",
"idx_wbytes": "0",
"idx_write": "0",
"idx_write_usecs": "0",
"invol_cs": "0",
"last_update": "0.000000",
"mail_cache_hits": "0",
"mail_lookup_attr": "0",
"mail_lookup_path": "0",
"mail_read_bytes": "0",
"mail_read_count": "0",
"maj_faults": "0",
"min_faults": "0",
"num_cmds": "0",
"num_connected_sessions": "0",
"num_logins": "0",
"obox_copy": "0",
"obox_del": "0",
"obox_iter": "0",
"obox_read": "0",
"obox_read_usecs": "0",
"obox_stat": "0",
"obox_wbytes": "0",
"obox_write": "0",
"obox_write_usecs": "0",
"read_bytes": "0",
"read_count": "0",
"reset_timestamp": "1483104199",
"sys_cpu": "0.0",
"user_cpu": "0.0",
"vol_cs": "0",
"write_bytes": "0",
"write_count": "0"
}
],
"aa"
]
]

CLI: doveadm stats dump global
</nowiki>

=== doveadm stats reset ===
reset dovecot statistics counters
<nowiki>

{
"command": "statsReset",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|}

example:

<nowiki>
[
[
"statsReset",
{},
"aa"
]
]

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

CLI: doveadm stats reset
</nowiki>

== doveadm penalty ==

<nowiki>
show current penalties

{
"command": "penalty",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "netmask",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|string
|Path to doveadm socket
|/var/run/dovecot-server
|-
|netmask
|string
|To reduce/filter the output supply an IP address or a network range in CIDR notation (ip/mask)
|10.0.0.0/24
|}

example:

<nowiki>
[
[
"penalty",
{},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["penalty",{},"aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm penalty
</nowiki>

== doveadm kick ==

Kick user from dovecot. Applicable to session in dovecot backend only

<nowiki>
{
"command": "kick",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "force",
"type": "boolean"
},
{
"name": "mask",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|force
|Boolean
|Do a forced kick?
|0
|-
|mask
|String
|Uid mask
|testuser001
|}

example:

<nowiki>
[
[
"kick",
{
"force": 0,
"mask": "testuser001"
},
"aa"
]
]

# curl -v -u doveadm:hellodoveadm –H “Content-Type: application/json" -d '[["kick", {"mask":"testuser001"}, "aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm kick testuser001
</nowiki>

response for succesfull kick:

<nowiki>
[
[
"doveadmResponse",
[
{
"result": "testuser001"
}
],
"aa"
]
]
</nowiki>

response in case kick failed:

<nowiki>
[
[
"error",
{
"exitCode": 68,
"type": "exitCode"
},
"aa"
]
]
</nowiki>

== doveadm who ==

<nowiki>
list active dovecot sessions

{
"command": "who",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "separateConnections",
"type": "boolean"
},
{
"name": "mask",
"type": "array"
}
]
}
</nowiki>

parameters

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|string
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|separateConnections
|Boolean
|Show each user connection in separate entries
|0
|-
|mask
|string array
|Uid mask
|testuser001
|}

Example:

<nowiki>
[
[
"who",
{
"mask": "",
"separateConnections": 0,
"socketPath": ""
},
"aa"
]
]

# curl -v -u doveadm:hellodoveadm -X POST http://localhost:ype: application/json" -d '[["who", {}, "aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm who
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"connections": "1",
"ips": "(127.0.0.1)",
"pids": "(4999)",
"service": "imap",
"username": "testuser001"
}
],
"aa"
]
]
</nowiki>

== doveadm director ==
=== doveadm director status ===

Show backend statuses on directors. Available only in directors

<nowiki>
[
{
"command": "directorStatus",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "tag",
"type": "string"
}
]
}
]
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|String
|Show director status for Tagged hosts only
|NewBackend
|}

example:

<nowiki>
[
[
"directorStatus",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorStatus",{},"bb"]]' http://localhost:8080/doveadm/v1

</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"mail server ip": "10.0.0.234",
"state": "up",
"state-changed": "2016-12-15 08:31:37",
"tag": "",
"users": "1",
"vhosts": "100"
},
{
"mail server ip": "10.0.0.235",
"state": "up",
"state-changed": "2016-12-15 08:31:04",
"tag": "",
"users": "0",
"vhosts": "100"
}
],
"bb"
]
]

CLI: doveadm director status
</nowiki>

=== doveadm director map ===

list current user → host mappings. Applicable to director only

<nowiki>

"command": "directorMap",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "usersFile",
"type": "string"
},
{
"name": "hashMap",
"type": "boolean"
},
{
"name": "userMap",
"type": "boolean"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

parameters

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|usersFile
|String
|provide Path to users list. One username per line
|/etc/dovecot/userlist.txt
|-
|hashMap
|Boolean
|Output users as hashmap
|True
|-
|userMap
|Boolean
|Output users as userlist
|True
|-
|host
|String
|Show only mappings to given host
|10.0.0.234
|}

example:

<nowiki>
[
[
"directorMap",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorMap",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"expire time": "2016-12-30 14:52:56",
"hash": "3853430566",
"mail server ip": "10.0.0.235",
"user": "samik"
}
],
"bb"
]
]

CLI: doveadm director map
</nowiki>

=== doveadm director add ===

add backend to director ring

<nowiki>
{
"command": "directorAdd",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "tag",
"type": "string"
},
{
"name": "host",
"type": "string"
},
{
"name": "vhostCount",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|tag
|String
|apply tag to backend
|/etc/dovecot/userlist.txt
|-
|host
|String
|backend ip to add
|10.0.0.234
|-
|vhostCount
|String
|vhost count to add
|100
|}

Example:

<nowiki>
[
[
"directorAdd",
{
"host": "10.0.234"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorAdd",{"host":"10.0.234"},"bb"]]' http://localhost:8080/doveadm/v1

CLI: doveadm director add 10.0.0.234
</nowiki>

=== doveadm director update ===

<nowiki>
{
"command": "directorUpdate",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
},
{
"name": "vhostCount",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|string
|Show director status for tagged hosts only
|NewBackend
|}

=== doveadm director up ===

<nowiki>
{
"command": "directorUp",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|string
|Show director status for tagged hosts only
|NewBackend
|}

=== doveadm director down ===

<nowiki>
{
"command": "directorDown",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|string
|Show director status for tagged hosts only
|NewBackend
|}

=== doveadm director remove ===

remove backend from director ring

<nowiki>
{
"command": "directorRemove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|host
|String
|backend to remove
|10.0.0.134
|}

example:

<nowiki>
[
[
"directorRemove",
{
"host": "10.0.0.234"
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRemove",{"host":"10.0.0.234"},"aa"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"aa"
]
]

CLI: doveadm director remove 10.0.0.234
</nowiki>

=== doveadm director move ===

move user mapping from backend to another or create director mapping for an user
<nowiki>
{
"command": "directorMove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|user
|String
|User uid to move
|testuser001
|-
|host
|string
|Target backend ip as listed in doveadm doveadm director status
|10.0.0.234
|}

example:

<nowiki>
[
[
"directorMove",
{
"host": "10.0.234",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorMove",{"user":"samik","host":"10.0.234"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director move samik 10.0.0.234
</nowiki>

== doveadm director kick ==

<nowiki>
{
"command": "directorKick",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|user
|String
|uid of user to kick
|samik
|}

example:

<nowiki>
[
[
"directorKick",
{
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorKick",{"user":"samik"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director kick samik
</nowiki>

=== doveadm director flush ===

flush connection mappings to one backend at director level. All users mapped to given host will be flushed from the hashmap table and will be redistributed to backends.

Parameters:

<nowiki>
{
"command": "directorFlush",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "forceFlush",
"type": "boolean"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|forceFlush
|Boolean
|Flag to make flush forced
|True
|-
|host
|String
|Backend ip address from doveadm director status list
|10.0.0.234
|}

example:

<nowiki>
[
[
"directorFlush",
{
"host": "10.0.0.234"
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorFlush",{"host":"10.0.0.234"},"aa"]]' http://localhost:8080/doveadm/v1

</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"aa"
]
]
CLI: doveadm director flush 10.0.234
</nowiki>

=== doveadm director dump ===

Dumb the current director backend host configuration as commands

<nowiki>
{
"command": "directorDump",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|}

example:

<nowiki>
[
[
"directorDump",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorDump",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"command": "add",
"host": "10.0.0.234",
"socket-path": "/var/run/dovecot/director-admin",
"vhost_count": "100"
},
{
"command": "add",
"host": "10.0.0.235",
"socket-path": "/var/run/dovecot/director-admin",
"vhost_count": "100"
}
],
"bb"
]
]

CLI: doveadm director dump
</nowiki>

=== doveadm director ring add ===

add new director to director ring

parameters:

<nowiki>
{
"command": "directorRingAdd",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "ip",
"type": "string"
},
{
"name": "port",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|ip
|String
|director ip address to add
|10.0.0.233
|-
|port
|String
|port number to use if not default
|9143
|}

example:

<nowiki>
[
[
"directorRingAdd",
{
"ip": "10.0.0.233"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRingAdd",{"ip":"10.0.0.233"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director ring add 10.0.0.233
</nowiki>

=== doveadm director ring remove ===

remove director from director ring

parameters:

<nowiki>
{
"command": "directorRingRemove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "ip",
"type": "string"
},
{
"name": "port",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|ip
|String
|director ip to remove
|10.0.0.233
|-
|port
|String
|director service port if not default
|9143
|}

example:

<nowiki>
[
[
"directorRingRemove",
{
"ip": "10.0.0.233"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRingRemove",{"ip":"10.0.0.233"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director ring remove 10.0.0.233
</nowiki>

=== doveadm director ring status ===

show director ring status

parameters:

<nowiki>

{
"command": "directorRingStatus",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|}

example:

<nowiki>
[
[
"directorRingStatus",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRingStatus",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>

[
"doveadmResponse",
[
{
"director ip": "10.0.0.232",
"last failed": "never",
"port": "9143",
"status": "synced",
"type": "self"
},
{
"director ip": "10.0.0.233",
"last failed": "never",
"port": "9143",
"status": "",
"type": ""
}
],
"bb"
]
]

CLI: doveadm director ring status
</nowiki>

== doveadm proxy ==

The doveadm proxy commands are used to list or kick active Dovecot proxy connections.

=== doveadm proxy list ===

list active connections in the dovecot proxy

parameters:

<nowiki>
{
"command": "proxyList",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|}

example:

<nowiki>
[
[
"proxyList",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["proxyList",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"dest-ip": "127.0.0.1",
"dest-port": "1143",
"service": "imap",
"src-ip": "10.0.0.153",
"username": "samik"
}
],
"bb"
]
]

CLI: doveadm proxy list
</nowiki>

=== doveadm proxy kick ===

kick user session from proxy. applicable to imap/pop3/managesieve sessions

parameters:

<nowiki>
{
"command": "proxyKick",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|userid to kick
|samik
|}

example:

<nowiki>
[
[
"proxyKick",
{
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["proxyKick",{"user":"samik"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"count": "1"
}
],
"bb"
]
]

CLI: doveadm proxy kick samik
</nowiki>

== doveadm logs errors ==

fetch errors log

paraments:

<nowiki>
{
"command": "logErrors",
"parameters": [
{
"name": "since",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|}

example:

<nowiki>
[
[
"logErrors",
{},
"a2"
]
]

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

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"prefix": "stats",
"text": "Stats client input error: Invalid level",
"timestamp": "Dec 09 16:24:00",
"type": "Error"
},
{
"prefix": "doveadm(127.0.0.1)",
"text": "read(/var/run/dovecot/stats) unexpectedly disconnected",
"timestamp": "Dec 09 16:24:00",
"type": "Fatal"
},
{
"prefix": "stats",
"text": "Stats client input error: Invalid level",
"timestamp": "Dec 09 16:24:22",
"type": "Error"
},
{
"prefix": "stats",
"text": "Stats client input error: Invalid level",
"timestamp": "Dec 09 16:27:48",
"type": "Error"
},
{
"prefix": "director",
"text": "Empty server list",
"timestamp": "Dec 09 16:29:13",
"type": "Error"
},
{
"prefix": "director",
"text": "Invalid value for director_mail_servers setting",
"timestamp": "Dec 09 16:29:13",
"type": "Fatal"
}
],
"a2"
]
]

CLI: doveadm log errors
</nowiki>

== doveadm dict ==
=== doveadm dict get ===

get user key value from configured dictionary

parameters:

<nowiki>
{
"command": "dictGet",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to query
|samik
|-
|dictUri
|String
|optional URI for dictionary to query
|
|-
|key
|String
|key to query
|
|}

=== doveadm dict set ===

set user key value in configured dictionary

parameters:

<nowiki>
{
"command": "dictSet",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
},
{
"name": "value",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|samik
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|key
|String
|dictionary key to modify
|
|-
|value
|string
|value to set
|
|}

=== doveadm dict unset ===

unset user key value in configured dictionary

parameters:

<nowiki>
{
"command": "dictUnset",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|key
|String
|dictionary key to unset
|
|}
== doveadm dict inc ==

increase users key value in dictionary

parameters:

<nowiki>
{
"command": "dictInc",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
},
{
"name": "difference",
"type": "integer"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|-
|key
|String
|dictionary key to increase
|
|-
|difference
|integer
|increment value
|
|}

=== doveadm dict iter ===

list user keys in dictionary

parameters:

<nowiki>
{
"command": "dictIter",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "exact",
"type": "boolean"
},
{
"name": "recurse",
"type": "boolean"
},
{
"name": "noValue",
"type": "boolean"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "prefix",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|exact
|Boolean
|list only exact matches
|
|-
|recurce
|Boolean
|do recursive search
|
|-
|noValue
|Boolean
|list also keys that have no value set
|
|-
|prefix
|String
|search only keys with given prefix
|
|}

== doveadm fs ==
=== doveadm fs get ===

get object from storage

parameters:

<nowiki>
{
"command": "fsGet",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem to fetch
|
|}

=== doveadm fs put ===

put object to storage

parameters:

<nowiki>
{
"command": "fsPut",
"parameters": [
{
"name": "hash",
"type": "string"
},
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "inputPath",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|hash
|string
|
|
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|inputPath
|String
|source object path in local filesystem
|
|-
|path
|String
|object path filesystem to put
|
|}

=== doveadm fs copy ===

copy object in storage

parameters:

<nowiki>
{
"command": "fsCopy",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "sourcePath",
"type": "string"
},
{
"name": "destinationPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|sourcePath
|String
|source object path
|
|-
|Destination path
|String
|destination object path in filesystem
|
|}

=== doveadm fs stat ===

fetch fs driver statistics

parameters:

<nowiki>
{
"command": "fsStat",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem fetch statistics for
|
|}

=== doveadm fs metadata ===

get filesystem object metadata

parameters:

<nowiki>
{
"command": "fsMetadata",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem fetch metadata for
|
|}

=== doveadm fs delete ===

delete object from storage

<nowiki>
{
"command": "fsDelete",
"parameters": [
{
"name": "recursive",
"type": "boolean"
},
{
"name": "maxParallel",
"type": "integer"
},
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem to delete
|
|-
|recursive
|Boolean
|do a recursive delete of path
|
|-
|maxParallel
|integer
|max number of parallel workers
|
|}

=== doveadm fs iter ===

list objects in given fs path

parameters:

<nowiki>
{
"command": "fsIter",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|path in filesystem to list
|
|}

=== doveadm fs iter-dirs ===
ist subfolders in given path

parameters:

<nowiki>
{
"command": "fsIterDirs",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|path in filesystem to list for subfolders
|
|}

== doveadm auth cache flush ==

flush authentication cache for one user or all users

parameters:

<nowiki>
{
"command": "authCacheFlush",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String array
|optional list of users in flush
|[“samik”,”samitest”]
|}

example:

<nowiki>
[
[
"authCacheFlush",
{
"user": [
"samik"
]
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["authCacheFlush",{"user":["samik"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"entries": "0"
}
],
"bb"
]
]

CLI: doveadm auth cache flush samik
</nowiki>

== doveadm user ==

do a userdb lookup for an user

<nowiki>
{
"command": "user",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "authInfo",
"type": "array"
},
{
"name": "field",
"type": "string"
},
{
"name": "expandField",
"type": "string"
},
{
"name": "userdbOnly",
"type": "boolean"
},
{
"name": "userMask",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|authInfo
|String array
|auth_info specifies additional conditions for the user command. The auth_info option string has to be given as name=value pair. For multiple conditions the -x option could be supplied multiple times.
Possible names for the auth_info are:
service
The service for which the userdb lookup should be tested. The value may be the name of a service, commonly used with Dovecot. For example: imap, pop3 or smtp.
lip
The local IP address (server) for the test.
rip
The remote IP address (client) for the test.
lport
The local port, e.g. 143
rport
The remote port, e.g. 24567
|sevice=imap
|-
|field
|String
|fetch only one specified field instead of all
|
|-
|expandField
|String
|expand configuration variable with user specific values
|
|-
|userdbOnly
|Boolean
|only fetch from userdb lookup and don’t process passdb
|
|-
|userMask
|String array
|search filter
|
|}

example:

<nowiki>
[
[
"user",
{
"userMask": [
"samik"
]
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["user",{"userMask":["samik"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
{
"samik": {
"gid": "1000",
"home": "/var/vmail/samik",
"junkflag": "0",
"mail": "Maildir:/mails/mails/samik/Maildir",
"namespace/Junk/hidden": "no",
"namespace/Junk/list": "yes",
"uid": "1000"
}
},
"bb"
]
]

CLI: doveadm user samik
</nowiki>

== doveadm mailbox ==
=== doveadm mailbox metadata set ===

set user mailbox metadata

parameters:

<nowiki>
{
"command": "mailboxMetadataSet",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "key",
"type": "string"
},
{
"name": "value",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata set
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to set
|
|-
|value
|String
|metadata value to set
|
|}

example:

<nowiki>
[
[
"mailboxMetadataSet",
{
"key": "/private/comment",
"mailbox": "INBOX",
"user": "samik",
"value": "test"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataSet",{"user":"samik","mailbox":"INBOX","key":"/private/comment","value":"test"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox metadata set –u samik INBOX /private/comment test
</nowiki>

=== doveadm mailbox metadata unset ===

unset user mailbox metadata

parameters:

<nowiki>
{
"command": "mailboxMetadataUnset",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata unset
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to unset
|
|}

example:

<nowiki>
[
[
"mailboxMetadataUnset",
{
"key": "/private/comment",
"mailbox": "INBOX",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataUnset",{"user":"samik","mailbox":"INBOX","key":"/private/comment"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox metadata unset –u samik INBOX /private/comment
</nowiki>

=== doveadm mailbox metadata get ===

get user mailbox metadata

parameters:

<nowiki>
{
"command": "mailboxMetadataGet",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata get
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to get
|
|}

example:

<nowiki>
[
[
"mailboxMetadataGet",
{
"key": "/private/comment",
"mailbox": "INBOX",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataGet",{"user":"samik","mailbox":"INBOX","key":"/private/comment"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response

<nowiki>
[
[
"doveadmResponse",
[
{
"value": "plaa"
}
],
"bb"
]
]

CLI: doveadm mailbox metadata get –u samik INBOX /private/comment
</nowiki>

=== doveadm mailbox list ===

list user mailbox metadata for a folder

parameters:

<nowiki>

"command": "mailboxMetadataList",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "keyPrefix",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata get
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to get
|
|-
|keyPrefix
|String
|search prefix for keys
|
|-
|mailbox
|String
|mailbox to fetch metadata from
|
|}

example:

<nowiki>
[
[
"mailboxMetadataList",
{
"mailbox": "INBOX",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataList",{"user":"samik","mailbox":"INBOX"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"key": "comment"
},
{
"key": "specialuse"
}
],
"bb"
]
]

CLI: doveadm mailbox metadata list –u samik INBOX
</nowiki>

=== doveadm mailbox status ===

fetch user mailbox status

parameters:

<nowiki>
{
"command": "mailboxStatus",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "totalSum",
"type": "boolean"
},
{
"name": "field",
"type": "array"
},
{
"name": "mailboxMask",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply status fetch
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|totalSum
|boolean
|
|
|-
|field
|String array
|fields to fetch
|all
|-
|mailboxMask
|String array
|fetch status on given mailboxes
|
|}

example:

<nowiki>

[
[
"mailboxStatus",
{
"field": [
"all"
],
"mailboxMask": [
"INBOX",
"INBOX/*",
"*"
],
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxStatus",{"user":"samik","field":["all"],"mailboxMask":["INBOX","INBOX/*","*"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"guid": "21b588150b156558eb3500007afd792c",
"highestmodseq": "5",
"mailbox": "Junk",
"messages": "0",
"recent": "0",
"uidnext": "1",
"uidvalidity": "1483019529",
"unseen": "0",
"vsize": "0"
},
{
"guid": "21b588150b156558eb3500007afd792c",
"highestmodseq": "5",
"mailbox": "INBOX",
"messages": "0",
"recent": "0",
"uidnext": "1",
"uidvalidity": "1483019529",
"unseen": "0",
"vsize": "0"
}
],
"bb"
]
]

CLI: doveadm mailbox status –u samik all “*”
</nowiki>

=== doveadm mailbox list ===

fetch user folder list

parameters:

<nowiki>
{
"command": "mailboxList",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mutf7",
"type": "boolean"
},
{
"name": "utf8",
"type": "boolean"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "mailboxMask",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid to apply mailbox list
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|mutf7
|Boolean
|
|
|-
|utf8
|Boolean
|fetch only certain fields instead of all
|
|-
|subscription
|Boolean
|
|
|-
|mailboxMask
|String array
|fetch list of given mailboxes
|
|}

example:

<nowiki>
[
[
"mailboxList",
{
"user": "samik"
},
"bb"
]
]
# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxList",{"user":"samik"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"mailbox": "Junk"
},
{
"mailbox": "INBOX"
}
],
"bb"
]
]

CLI: doveadm mailbox list –u samik
</nowiki>

=== doveadm mailbox create ===
create mailbox folder for user

parameters:

<nowiki>
{
"command": "mailboxCreate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "guid",
"type": "string"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply mailbox create
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|subscription
|Boolean
|
|
|-
|mailbox
|String array
|list of mailbox folders to create
|
|}

example:

<nowiki>
[
[
"mailboxCreate",
{
"mailbox": [
"INBOX/myfolder"
],
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxCreate",{"user":"samik","mailbox":["INBOX/myfolder"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>

[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox create –u samik INBOX/myfolder
</nowiki>

=== doveadm mailbox delete ===

delete user mailbox folder

parameters:

<nowiki>
{
"command": "mailboxDelete",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "requireEmpty",
"type": "boolean"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "recursive",
"type": "boolean"
},
{
"name": "unsafe",
"type": "boolean"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply delete
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|requireEmpty
|Boolean
|only delete if folder is empty
|
|-
|subscription
|Boolean
|
|
|-
|recursive
|Boolean
|delete also subfolders
|
|-
|unsafe
|Boolean
|
|
|-
|mailbox
|String array
|list of mailbox folders to create
|
|}

example:

<nowiki>
[
[
"mailboxDelete",
{
"mailbox": [
"INBOX/myfolder"
],
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxDelete",{"user":"samik","mailbox":["INBOX/myfolder"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox delete –u samik INBOX/myfolder
</nowiki>

=== doveadm mailbox rename ===

rename user folder

parameters:

<nowiki>
{
"command": "mailboxRename",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "newName",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply mailbox rename
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|subscriptions
|Boolean
|
|
|-
|newName
|String
|mailbox new name
|
|-
|mailbox
|String
|mailbox to rename
|
|}

example:

<nowiki>
[
[
"mailboxRename",
{
"mailbox": "INBOX/myfolder",
"newName": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxRename",{"user":"samik","mailbox":"INBOX/myfolder","newName":"INBOX/myfoldertoo"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox rename –u samik INBOX/myfolder INBOX/myfoldertoo
</nowiki>

=== doveadm mailbox subscribe ===

subscribe user to a mailbox

parameters:

<nowiki>
{
"command": "mailboxSubscribe",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply subscribe
|
|-
|userFile
|String
|optionally fetch usernames from. One username per line
|
|-
|mailbox
|String
|mailbox to subscribe
|
|}

example:

<nowiki>
[
[
"mailboxSubscribe",
{
"mailbox": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxSubscribe",{"user":"samik","mailbox":"INBOX/myfoldertoo"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:
<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox subscribe –u samik INBOX/myfoldertoo
</nowiki>

=== doveadm mailbox unsubscribe ===

unsubscribe user from an folder

parameters:

<nowiki>
{
"command": "mailboxUnsubscribe",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply unsubscribe
|
|-
|userFile
|String
|optionally fetch usernames from. One username per line
|
|-
|mailbox
|String
|mailbox to unsubscribe
|
|}

example:

<nowiki>
[
[
"mailboxUnsubscribe",
{
"mailbox": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxUnsubscribe",{"user":"samik","mailbox":"INBOX/myfoldertoo"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox unsubscribe –u samik INBOX/myfoldertoo
</nowiki>

=== doveadm mailbox update ===

update user mailbox information

parameters:

<nowiki>
{
"command": "mailboxUpdate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailboxGuid",
"type": "string"
},
{
"name": "uidValidity",
"type": "string"
},
{
"name": "minNextUid",
"type": "string"
},
{
"name": "minFirstRecentUid",
"type": "string"
},
{
"name": "minHighestModseq",
"type": "string"
},
{
"name": "minHighestPvtModseq",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply update
|
|-
|userFile
|String
|optionally fetch usernames from. One username per line
|
|-
|mailbox
|String
|mailbox to unsubscribe
|
|-
|mailboxGuid
|String
|set mailbox guid
|
|-
|uidValidity
|String
|set mailbox uidvalidity
|
|-
|minNextuid
|String
|set mailbox minimum next uid
|
|-
|minFirstRecentuid
|String
|set mailbox minimum recent uid
|
|-
|minHighestModseq
|String
|
|
|-
|minHighestPvtModseq
|String
|
|
|}

=== doveadm mailbox save ===

save mail into users mailbox

parameters:

<nowiki>
{
"command": "save",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "file",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to save mail into
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|mailbox
|String
|mailbox to unsubscribe
|
|-
|file
|String
|mail to inject
|
|}

example:

<nowiki>
[
[
"save",
{
"file": "From: Joulu Pukki <joulu.pukki@korvatunturi.fi>\nSubject: plaa\n\nmail body\n",
"mailbox": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["save",{"user":"samik","mailbox":"INBOX/myfoldertoo","file":"From: Joulu Pukki <joulu.pukki@korvatunturi.fi>\nSubject: plaa\n\nmail body\n"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]
</nowiki>

== doveadm fetch ==

fetch data from user mailbox

parameters:

<nowiki>
{
"command": "fetch",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "field",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to fetch data
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|field
|String array
|fields to fetch. Supported fields as of dovecot 2.2.26: hdr.<name> body.<section> binary.<section> user mailbox mailbox-guid seq uid guid flags modseq hdr body body.snippet text text.utf8 size.physical size.virtual date.received date.sent date.saved date.received.unixtime date.sent.unixtime date.saved.unixtime imap.envelope imap.body imap.bodystructure pop3.uidl pop3.order refcount storageid
|
|-
|query
|String array
|search query to user
|
|}

example:

<nowiki>
[
[
"fetch",
{
"field": [
"text"
],
"query": [
"mailbox",
"INBOX/myfoldertoo"
],
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["fetch",{"user":"samik","field":["text"],"query":["mailbox","INBOX/myfoldertoo"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"text": "From: Joulu Pukki <joulu.pukki@korvatunturi.fi>\nSubject: plaa\n\nmail body\n"
}
],
"bb"
]
]

CLI: doveadm fetch –u samik “text” mailbox INBOX/myfoldertoo
</nowiki>

== doveadm index ==

index user mailbox folder or folders

parameters:

<nowiki>
{
"command": "index",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "queue",
"type": "boolean"
},
{
"name": "maxRecent",
"type": "string"
},
{
"name": "mailboxMask",
"type": "string"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to index
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|query
|Boolean
|max number of recent mails to index
|
|-
|maxRecent
|String
|max number of recent mails to index
|
|-
|mailboxMask
|String
|mailbox search mask to apply indexing into
|
|}

example:

<nowiki>
[
[
"index",
{
"mailboxMask": "INBOX*",
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["index",{"user":"samik","mailboxMask":"INBOX*"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm index –u samik “INBOX*”
</nowiki>

== doveadm altmove ==

move mails between primary and alternative mailbox storage locations. Applicable to mdbox and sdbox mailbox formats only

parameters:

<nowiki>
{
"command": "altmove",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "reverse",
"type": "boolean"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to apply move
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|reverse
|Boolean
|search query to apply to mail move
|
|-
|query
|String array
|search query to apply to mail move
|
|}

example:

<nowiki>
[
[
"altmove",
{
"query": [
"mailbox",
"INBOX/myfoldertoo",
"savedbefore",
"since",
"30d"
],
"reverse": 0,
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["altmove",{"user":"samik","reverse":0,"query":["mailbox","INBOX/myfoldertoo","savedbefore","since","30d"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

== doveadm deduplicate ==

This command is used to expunge duplicated messages in mailboxes

parameters:

<nowiki>
{
"command": "deduplicate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "byMsgid",
"type": "boolean"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to deduplicate
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|byMsgId
|Boolean
|deduplicate by Message-ID instead of guid
|
|-
|query
|String array
|search query to apply to deduplicate
|
|}

== doveadm expunge ==

Expunge messages matching given search query

parameters:

<nowiki>
{
"command": "expunge",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "deleteEmptyMailbox",
"type": "boolean"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to expunge
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|deleteEmptyMailbox
|Boolean
|delete also mailbox if it’s empty after expunge has been applied
|
|-
|query
|String array
|search query to apply to expunge
|
|}

== doveadm flags ==
add, remove or replace messages' flags

=== doveadm flags add ===

add flag to a message or messages

parameters:

<nowiki>
{
"command": "flagsAdd",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "flag",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to add flags
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|flag
|String array
|list of flags to add
|
|-
|query
|String array
|search query to apply to flag add
|
|}

=== doveadm flags remove ===

remove flags from message or messages

parameters:

<nowiki>
{
"command": "flagsRemove",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "flag",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to add flags
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|flag
|String array
|list of flags to remove
|
|-
|query
|String array
|search query to apply to flag remove
|
|}

=== doveadm flags replace ===

Replace flags with another flag in message or messages. Replaces all current flags with the ones in the parameter list

parameters:

<nowiki>
{
"command": "flagsReplace",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "flag",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to replace flags
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|flag
|String array
|list of flags to replace with
|
|-
|query
|String array
|search query to apply to flag replace
|
|}

== doveadm import ==

Import messages matching given search query

parameters:

<nowiki>
{
"command": "import",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "subscribe",
"type": "boolean"
},
{
"name": "sourceLocation",
"type": "string"
},
{
"name": "destParentMailbox",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to apply import
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|subscribe
|boolean
|when enabled possible newly created folders are also subscibed
|
|-
|sourceLocation
|String
|location of source mailboxes
|
|-
|destParentMailbox
|String
|destination parent mailbox where to import
|
|-
|query
|String array
|search query for messages to import
|
|}

== doveadm force-resync ==

Under certain circumstances it may happen, that dovecot is unable to automatically solve problems with mailboxes. In such situations the force-resync command may be helpful. It tries to fix all problems. For sdbox and mdbox mailboxes the storage files will be also checked.

parameters:

<nowiki>
{
"command": "forceResync",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailboxMask",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|user
|String
|uid of user to apply resync
|
|-
|mailboxMask
|String
|apply forced resync on given mailboxes
|INBOX*
|}

example:

<nowiki>
[
[
"forceResync",
{
"mailboxMask": "INBOX*",
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["forceResync",{"user":"samik","mailboxMask":"INBOX*"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm force-resync –u samik “INBOX*”
</nowiki>

== doveadm purge ==

Remove messages with refcount=0 from mdbox files

parameters:

<nowiki>
{
"command": "purge",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to apply purge
|
|}

== doveadm search ==

Show a list of mailbox GUIDs and message UIDs matching given search query

parameters:

<nowiki>
{
"command": "search",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|user
|String
|uid of user to apply purge
|
|-
|query
|String array
|search query
|
|}

example:

<nowiki>
[
[
"search",
{
"query": [
"mailbox",
"INBOX*",
"all"
],
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["search",{"user":"samik","query":["mailbox","INBOX*","all"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"mailbox-guid": "cf497f128caf7c58612200007afd792c",
"uid": "1"
}
],
"bb"
]
]

CLI: doveadm search –u samik mailbox “INBOX*” all
</nowiki>

== doveadm copy ==

Copy messages matching the given search query into another mailbox

parameters:

<nowiki>
{
"command": "copy",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "destinationMailbox",
"type": "string"
},
{
"name": "sourceType",
"type": "string"
},
{
"name": "sourceUser",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm move ==

Move messages matching the given search query into another mailbox

parameters:

<nowiki>
{
"command": "move",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "destinationMailbox",
"type": "string"
},
{
"name": "sourceType",
"type": "string"
},
{
"name": "sourceUser",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm fscache rescan ==

force fscache rescan

parameters:

<nowiki>
{
"command": "fscacheRescan",
"parameters": [
{
"name": "path",
"type": "string"
},
{
"name": "maxAge",
"type": "integer"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm metacache ==
=== doveadm metacache clean ===

clean metacache content for given user or all users

parameters:

<nowiki>
{

"command": "metacacheClean",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "days",
"type": "integer"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache flush ===

flush metacache contents to storage for given user or all users

parameters:

<nowiki>
{
"command": "metacacheFlush",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache unpack ===

unpack metacache index bundle to target directory

parameters:

<nowiki>
{
"command": "metacacheUnpack",
"parameters": [
{
"name": "bundleName",
"type": "string"
},
{
"name": "bundle",
"type": "string"
},
{
"name": "destinationDirectory",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache flushall ===

flush metacache to storage for all users

parameters:

<nowiki>
{
"command": "metacacheFlushall",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache remove ===

remove metacache for given mask

parameters:

<nowiki>
{
"command": "metacacheRemove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "mask",
"type": "string"
}
]
}
</nowiki>
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache list ===

list local metacache contents

parameters:

<nowiki>
{
"command": "metacacheList",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm obox user delete ==

delete user data from storage, Cassandra and local caches (metacache and fscache).

parameters:

<nowiki>
{
"command": "oboxUserDelete",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

example:

<nowiki>
[
[
"oboxUserDelete",
{
"allUsers": 0,
"socketPath": "",
"user": "testuser003",
"userFile": ""
},
"aa"
]
]

# curl -v -u doveadm:hellodoveadm -X POST http://localhost:ype: application/json" -d '[["oboxUserDelete", {"allUsers":0,"user":"testuser003"}, "aa"]]'
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"aa"
]
]

CLI: doveadm obox user delete –u testuser003
</nowiki>

== doveadm sieve ==

Commands related to handling Sieve scripts.

=== doveadm sieve list ===

list user sieve scripts

parameters:

<nowiki>
{
"command": "sieveList",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve get ===

get user sieve script

parameters:

<nowiki>
{
"command": "sieveGet",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "scriptname",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve put ===

inject sieve script to user

parameters:

<nowiki>
{
"command": "sievePut",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "activate",
"type": "boolean"
},
{
"name": "scriptname",
"type": "string"
},
{
"name": "file",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve delete ===

delete user sieve

parameters:

<nowiki>
{
"command": "sieveDelete",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "ignoreActive",
"type": "boolean"
},
{
"name": "scriptname",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve activate ===

activate user sieve script

parameters:

<nowiki>
{
"command": "sieveActivate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "scriptname",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve deactivate ===

deactivate user sieve

parameters:

<nowiki>
{
"command": "sieveDeactivate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve rename ===

rename user sieve script

parameters:

<nowiki>
{
"command": "sieveRename",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "oldname",
"type": "string"
},
{
"name": "newname",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm fts ==
Dovecot fts indexing commands.

=== doveadm fts lookup ===

query user fts indexed data

parameters:

<nowiki>
{
"command": "ftsLookup",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts expand ===

<nowiki>
{
"command": "ftsExpand",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts tokenize ===

<nowiki>
{
"command": "ftsTokenize",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "language",
"type": "string"
},
{
"name": "text",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts optimize ===

<nowiki>
{
"command": "ftsOptimize",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts rescan ===

<nowiki>
{
"command": "ftsRescan",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

Template:DoveadmHTTPapi

2017-03-15T12:19:25Z

Oskarikentta: /* doveadm fs metadata */

== Table of Contents ==
__TOC__

== 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:

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

=== 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:

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

Basic auth usage:
<nowiki>
curl -H "Authorization: Basic <base64 doveadm:doveadm_password>"
http://host:port/doveadm/v1
</nowiki>
or by letting curl to form the base64 encoded authentication basig authentication header:

<nowiki>
curl –u doveadm:password http://host:port/doveadm/v1
</nowiki>

=== 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:

<nowiki>

[
[
"command1",
{
"parameter1": "value",
"parameter2": "value",
"parameter3": "value"
},
"identifier"
]
]
</nowiki>
Multiple commands can be submitted in one json payload:
<nowiki>
[
[
"command1",
{
"parameter1": "value",
"parameter2": "value"
},
"identifier1"
],
[
"command2",
{
"parameter1": "value",
"parameter2": "value"
},
"identifier2"
]
]
</nowiki>

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:

<nowiki>

son payload:

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

</nowiki>

submitting the command with curl:

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

command line equivalent

doveadm reload

=== successful response ===

<nowiki>

[
[
"doveadmResponse",
[],
"a2"
]
]
</nowiki>

=== failure response ===

<nowiki>

[
[
"error",
{
"exitCode": 68,
"type": "exitCode"
},
"a2"
]
</nowiki>

=== failure codes ===

{| class="wikitable"
|-
|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
|}

== Supported commands ==

== doveadm service ==
=== doveadm service stop ===

stop one or more dovecot services on target host

<nowiki>
{
"command": "serviceStop",
"parameters": [
{
"name": "service",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|service
|string array
|Name of service to stop
|[“imap”,”imap-hibernate”]
|}

example:

<nowiki>
[
[
"serviceStop",
{
"service": [
"imap",
"imap-hibernate"
]
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["serviceStop",{"service":["imap","imap-hibernate"]},"aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm service stop imap imap-hibernate
</nowiki>

=== doveadm stop ===

stop dovecot on the target host
<nowiki>

{
"command": "stop",
"parameters": []
}

no parameters
</nowiki>
example:
<nowiki>
[
[
"stop",
{},
"a1"
]
]

# curl -u doveadm:hellodoveadm -X POST http://localhost:8080/doveadm/v1 -H "Content-Type: application/json" -d '[["stop",{},"a1"]]'

CLI: doveadm stop
</nowiki>

=== doveadm reload ===

reload dovecot configuration

<nowiki>
{
"command": "reload",
"parameters": []
}
</nowiki>

example:

<nowiki>
[
[
"reload",
{},
"a2"
]
]

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

CLI: doveadm reload
</nowiki>

== doveadm stats ==
=== doveadm stats dump ===

dump collected dovecot statistics

<nowiki>
{
"command": "statsDump",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "type",
"type": "string"
},
{
"name": "filter",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|+parameters
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|type
|String
|Type of stats to dump
|global
|-
|filter
|String
|Dump filter
|last_update 1483101542
|}

Example:

<nowiki>
[
[
"statsDump",
{
"type": "global"
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["statsDump",{"type":"global"},"aa"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"auth_cache_hits": "0",
"auth_cache_misses": "0",
"auth_db_tempfails": "0",
"auth_failures": "0",
"auth_master_successes": "0",
"auth_successes": "0",
"clock_time": "0.0",
"disk_input": "0",
"disk_output": "0",
"fscache_read": "0",
"fscache_stat": "0",
"fscache_write": "0",
"idx_del": "0",
"idx_iter": "0",
"idx_read": "0",
"idx_read_usecs": "0",
"idx_wbytes": "0",
"idx_write": "0",
"idx_write_usecs": "0",
"invol_cs": "0",
"last_update": "0.000000",
"mail_cache_hits": "0",
"mail_lookup_attr": "0",
"mail_lookup_path": "0",
"mail_read_bytes": "0",
"mail_read_count": "0",
"maj_faults": "0",
"min_faults": "0",
"num_cmds": "0",
"num_connected_sessions": "0",
"num_logins": "0",
"obox_copy": "0",
"obox_del": "0",
"obox_iter": "0",
"obox_read": "0",
"obox_read_usecs": "0",
"obox_stat": "0",
"obox_wbytes": "0",
"obox_write": "0",
"obox_write_usecs": "0",
"read_bytes": "0",
"read_count": "0",
"reset_timestamp": "1483104199",
"sys_cpu": "0.0",
"user_cpu": "0.0",
"vol_cs": "0",
"write_bytes": "0",
"write_count": "0"
}
],
"aa"
]
]

CLI: doveadm stats dump global
</nowiki>

=== doveadm stats reset ===
reset dovecot statistics counters
<nowiki>

{
"command": "statsReset",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|}

example:

<nowiki>
[
[
"statsReset",
{},
"aa"
]
]

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

CLI: doveadm stats reset
</nowiki>

== doveadm penalty ==

<nowiki>
show current penalties

{
"command": "penalty",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "netmask",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|string
|Path to doveadm socket
|/var/run/dovecot-server
|-
|netmask
|string
|To reduce/filter the output supply an IP address or a network range in CIDR notation (ip/mask)
|10.0.0.0/24
|}

example:

<nowiki>
[
[
"penalty",
{},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["penalty",{},"aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm penalty
</nowiki>

== doveadm kick ==

Kick user from dovecot. Applicable to session in dovecot backend only

<nowiki>
{
"command": "kick",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "force",
"type": "boolean"
},
{
"name": "mask",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|force
|Boolean
|Do a forced kick?
|0
|-
|mask
|String
|Uid mask
|testuser001
|}

example:

<nowiki>
[
[
"kick",
{
"force": 0,
"mask": "testuser001"
},
"aa"
]
]

# curl -v -u doveadm:hellodoveadm –H “Content-Type: application/json" -d '[["kick", {"mask":"testuser001"}, "aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm kick testuser001
</nowiki>

response for succesfull kick:

<nowiki>
[
[
"doveadmResponse",
[
{
"result": "testuser001"
}
],
"aa"
]
]
</nowiki>

response in case kick failed:

<nowiki>
[
[
"error",
{
"exitCode": 68,
"type": "exitCode"
},
"aa"
]
]
</nowiki>

== doveadm who ==

<nowiki>
list active dovecot sessions

{
"command": "who",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "separateConnections",
"type": "boolean"
},
{
"name": "mask",
"type": "array"
}
]
}
</nowiki>

parameters

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|string
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|separateConnections
|Boolean
|Show each user connection in separate entries
|0
|-
|mask
|string array
|Uid mask
|testuser001
|}

Example:

<nowiki>
[
[
"who",
{
"mask": "",
"separateConnections": 0,
"socketPath": ""
},
"aa"
]
]

# curl -v -u doveadm:hellodoveadm -X POST http://localhost:ype: application/json" -d '[["who", {}, "aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm who
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"connections": "1",
"ips": "(127.0.0.1)",
"pids": "(4999)",
"service": "imap",
"username": "testuser001"
}
],
"aa"
]
]
</nowiki>

== doveadm director ==
=== doveadm director status ===

Show backend statuses on directors. Available only in directors

<nowiki>
[
{
"command": "directorStatus",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "tag",
"type": "string"
}
]
}
]
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|String
|Show director status for Tagged hosts only
|NewBackend
|}

example:

<nowiki>
[
[
"directorStatus",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorStatus",{},"bb"]]' http://localhost:8080/doveadm/v1

</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"mail server ip": "10.0.0.234",
"state": "up",
"state-changed": "2016-12-15 08:31:37",
"tag": "",
"users": "1",
"vhosts": "100"
},
{
"mail server ip": "10.0.0.235",
"state": "up",
"state-changed": "2016-12-15 08:31:04",
"tag": "",
"users": "0",
"vhosts": "100"
}
],
"bb"
]
]

CLI: doveadm director status
</nowiki>

=== doveadm director map ===

list current user → host mappings. Applicable to director only

<nowiki>

"command": "directorMap",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "usersFile",
"type": "string"
},
{
"name": "hashMap",
"type": "boolean"
},
{
"name": "userMap",
"type": "boolean"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

parameters

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|usersFile
|String
|provide Path to users list. One username per line
|/etc/dovecot/userlist.txt
|-
|hashMap
|Boolean
|Output users as hashmap
|True
|-
|userMap
|Boolean
|Output users as userlist
|True
|-
|host
|String
|Show only mappings to given host
|10.0.0.234
|}

example:

<nowiki>
[
[
"directorMap",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorMap",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"expire time": "2016-12-30 14:52:56",
"hash": "3853430566",
"mail server ip": "10.0.0.235",
"user": "samik"
}
],
"bb"
]
]

CLI: doveadm director map
</nowiki>

=== doveadm director add ===

add backend to director ring

<nowiki>
{
"command": "directorAdd",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "tag",
"type": "string"
},
{
"name": "host",
"type": "string"
},
{
"name": "vhostCount",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|tag
|String
|apply tag to backend
|/etc/dovecot/userlist.txt
|-
|host
|String
|backend ip to add
|10.0.0.234
|-
|vhostCount
|String
|vhost count to add
|100
|}

Example:

<nowiki>
[
[
"directorAdd",
{
"host": "10.0.234"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorAdd",{"host":"10.0.234"},"bb"]]' http://localhost:8080/doveadm/v1

CLI: doveadm director add 10.0.0.234
</nowiki>

=== doveadm director update ===

<nowiki>
{
"command": "directorUpdate",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
},
{
"name": "vhostCount",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|string
|Show director status for tagged hosts only
|NewBackend
|}

=== doveadm director up ===

<nowiki>
{
"command": "directorUp",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|string
|Show director status for tagged hosts only
|NewBackend
|}

=== doveadm director down ===

<nowiki>
{
"command": "directorDown",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|string
|Show director status for tagged hosts only
|NewBackend
|}

=== doveadm director remove ===

remove backend from director ring

<nowiki>
{
"command": "directorRemove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|host
|String
|backend to remove
|10.0.0.134
|}

example:

<nowiki>
[
[
"directorRemove",
{
"host": "10.0.0.234"
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRemove",{"host":"10.0.0.234"},"aa"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"aa"
]
]

CLI: doveadm director remove 10.0.0.234
</nowiki>

=== doveadm director move ===

move user mapping from backend to another or create director mapping for an user
<nowiki>
{
"command": "directorMove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|user
|String
|User uid to move
|testuser001
|-
|host
|string
|Target backend ip as listed in doveadm doveadm director status
|10.0.0.234
|}

example:

<nowiki>
[
[
"directorMove",
{
"host": "10.0.234",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorMove",{"user":"samik","host":"10.0.234"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director move samik 10.0.0.234
</nowiki>

== doveadm director kick ==

<nowiki>
{
"command": "directorKick",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|user
|String
|uid of user to kick
|samik
|}

example:

<nowiki>
[
[
"directorKick",
{
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorKick",{"user":"samik"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director kick samik
</nowiki>

=== doveadm director flush ===

flush connection mappings to one backend at director level. All users mapped to given host will be flushed from the hashmap table and will be redistributed to backends.

Parameters:

<nowiki>
{
"command": "directorFlush",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "forceFlush",
"type": "boolean"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|forceFlush
|Boolean
|Flag to make flush forced
|True
|-
|host
|String
|Backend ip address from doveadm director status list
|10.0.0.234
|}

example:

<nowiki>
[
[
"directorFlush",
{
"host": "10.0.0.234"
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorFlush",{"host":"10.0.0.234"},"aa"]]' http://localhost:8080/doveadm/v1

</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"aa"
]
]
CLI: doveadm director flush 10.0.234
</nowiki>

=== doveadm director dump ===

Dumb the current director backend host configuration as commands

<nowiki>
{
"command": "directorDump",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|}

example:

<nowiki>
[
[
"directorDump",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorDump",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"command": "add",
"host": "10.0.0.234",
"socket-path": "/var/run/dovecot/director-admin",
"vhost_count": "100"
},
{
"command": "add",
"host": "10.0.0.235",
"socket-path": "/var/run/dovecot/director-admin",
"vhost_count": "100"
}
],
"bb"
]
]

CLI: doveadm director dump
</nowiki>

=== doveadm director ring add ===

add new director to director ring

parameters:

<nowiki>
{
"command": "directorRingAdd",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "ip",
"type": "string"
},
{
"name": "port",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|ip
|String
|director ip address to add
|10.0.0.233
|-
|port
|String
|port number to use if not default
|9143
|}

example:

<nowiki>
[
[
"directorRingAdd",
{
"ip": "10.0.0.233"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRingAdd",{"ip":"10.0.0.233"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director ring add 10.0.0.233
</nowiki>

=== doveadm director ring remove ===

remove director from director ring

parameters:

<nowiki>
{
"command": "directorRingRemove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "ip",
"type": "string"
},
{
"name": "port",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|ip
|String
|director ip to remove
|10.0.0.233
|-
|port
|String
|director service port if not default
|9143
|}

example:

<nowiki>
[
[
"directorRingRemove",
{
"ip": "10.0.0.233"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRingRemove",{"ip":"10.0.0.233"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director ring remove 10.0.0.233
</nowiki>

=== doveadm director ring status ===

show director ring status

parameters:

<nowiki>

{
"command": "directorRingStatus",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|}

example:

<nowiki>
[
[
"directorRingStatus",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRingStatus",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>

[
"doveadmResponse",
[
{
"director ip": "10.0.0.232",
"last failed": "never",
"port": "9143",
"status": "synced",
"type": "self"
},
{
"director ip": "10.0.0.233",
"last failed": "never",
"port": "9143",
"status": "",
"type": ""
}
],
"bb"
]
]

CLI: doveadm director ring status
</nowiki>

== doveadm proxy ==

The doveadm proxy commands are used to list or kick active Dovecot proxy connections.

=== doveadm proxy list ===

list active connections in the dovecot proxy

parameters:

<nowiki>
{
"command": "proxyList",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|}

example:

<nowiki>
[
[
"proxyList",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["proxyList",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"dest-ip": "127.0.0.1",
"dest-port": "1143",
"service": "imap",
"src-ip": "10.0.0.153",
"username": "samik"
}
],
"bb"
]
]

CLI: doveadm proxy list
</nowiki>

=== doveadm proxy kick ===

kick user session from proxy. applicable to imap/pop3/managesieve sessions

parameters:

<nowiki>
{
"command": "proxyKick",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|userid to kick
|samik
|}

example:

<nowiki>
[
[
"proxyKick",
{
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["proxyKick",{"user":"samik"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"count": "1"
}
],
"bb"
]
]

CLI: doveadm proxy kick samik
</nowiki>

== doveadm logs errors ==

fetch errors log

paraments:

<nowiki>
{
"command": "logErrors",
"parameters": [
{
"name": "since",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|}

example:

<nowiki>
[
[
"logErrors",
{},
"a2"
]
]

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

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"prefix": "stats",
"text": "Stats client input error: Invalid level",
"timestamp": "Dec 09 16:24:00",
"type": "Error"
},
{
"prefix": "doveadm(127.0.0.1)",
"text": "read(/var/run/dovecot/stats) unexpectedly disconnected",
"timestamp": "Dec 09 16:24:00",
"type": "Fatal"
},
{
"prefix": "stats",
"text": "Stats client input error: Invalid level",
"timestamp": "Dec 09 16:24:22",
"type": "Error"
},
{
"prefix": "stats",
"text": "Stats client input error: Invalid level",
"timestamp": "Dec 09 16:27:48",
"type": "Error"
},
{
"prefix": "director",
"text": "Empty server list",
"timestamp": "Dec 09 16:29:13",
"type": "Error"
},
{
"prefix": "director",
"text": "Invalid value for director_mail_servers setting",
"timestamp": "Dec 09 16:29:13",
"type": "Fatal"
}
],
"a2"
]
]

CLI: doveadm log errors
</nowiki>

== doveadm dict ==
=== doveadm dict get ===

get user key value from configured dictionary

parameters:

<nowiki>
{
"command": "dictGet",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to query
|samik
|-
|dictUri
|String
|optional URI for dictionary to query
|
|-
|key
|String
|key to query
|
|}

=== doveadm dict set ===

set user key value in configured dictionary

parameters:

<nowiki>
{
"command": "dictSet",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
},
{
"name": "value",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|samik
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|key
|String
|dictionary key to modify
|
|-
|value
|string
|value to set
|
|}

=== doveadm dict unset ===

unset user key value in configured dictionary

parameters:

<nowiki>
{
"command": "dictUnset",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|key
|String
|dictionary key to unset
|
|}
== doveadm dict inc ==

increase users key value in dictionary

parameters:

<nowiki>
{
"command": "dictInc",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
},
{
"name": "difference",
"type": "integer"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|-
|key
|String
|dictionary key to increase
|
|-
|difference
|integer
|increment value
|
|}

=== doveadm dict iter ===

list user keys in dictionary

parameters:

<nowiki>
{
"command": "dictIter",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "exact",
"type": "boolean"
},
{
"name": "recurse",
"type": "boolean"
},
{
"name": "noValue",
"type": "boolean"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "prefix",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|exact
|Boolean
|list only exact matches
|
|-
|recurce
|Boolean
|do recursive search
|
|-
|noValue
|Boolean
|list also keys that have no value set
|
|-
|prefix
|String
|search only keys with given prefix
|
|}

== doveadm fs ==
=== doveadm fs get ===

get object from storage

parameters:

<nowiki>
{
"command": "fsGet",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem to fetch
|
|}

=== doveadm fs put ===

put object to storage

parameters:

<nowiki>
{
"command": "fsPut",
"parameters": [
{
"name": "hash",
"type": "string"
},
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "inputPath",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|hash
|string
|
|
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|inputPath
|String
|source object path in local filesystem
|
|-
|path
|String
|object path filesystem to put
|
|}

=== doveadm fs copy ===

copy object in storage

parameters:

<nowiki>
{
"command": "fsCopy",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "sourcePath",
"type": "string"
},
{
"name": "destinationPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|sourcePath
|String
|source object path
|
|-
|Destination path
|String
|destination object path in filesystem
|
|}

=== doveadm fs stat ===

fetch fs driver statistics

parameters:

<nowiki>
{
"command": "fsStat",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem fetch statistics for
|
|}

=== doveadm fs metadata ===

get filesystem object metadata

parameters:

<nowiki>
{
"command": "fsMetadata",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem fetch metadata for
|
|}

=== doveadm fs delete ===

delete object from storage

<nowiki>
{
"command": "fsDelete",
"parameters": [
{
"name": "recursive",
"type": "boolean"
},
{
"name": "maxParallel",
"type": "integer"
},
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem fetch statistics for
|
|-
|recursive
|Boolean
|do a recursive delete of path
|
|-
|maxParallel
|integer
|max number of parallel workers
|
|}

=== doveadm fs iter ===

list objects in given fs path

parameters:

<nowiki>
{
"command": "fsIter",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|path in filesystem to list
|
|}

=== doveadm fs iter-dirs ===
ist subfolders in given path

parameters:

<nowiki>
{
"command": "fsIterDirs",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|path in filesystem to list for subfolders
|
|}

== doveadm auth cache flush ==

flush authentication cache for one user or all users

parameters:

<nowiki>
{
"command": "authCacheFlush",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String array
|optional list of users in flush
|[“samik”,”samitest”]
|}

example:

<nowiki>
[
[
"authCacheFlush",
{
"user": [
"samik"
]
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["authCacheFlush",{"user":["samik"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"entries": "0"
}
],
"bb"
]
]

CLI: doveadm auth cache flush samik
</nowiki>

== doveadm user ==

do a userdb lookup for an user

<nowiki>
{
"command": "user",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "authInfo",
"type": "array"
},
{
"name": "field",
"type": "string"
},
{
"name": "expandField",
"type": "string"
},
{
"name": "userdbOnly",
"type": "boolean"
},
{
"name": "userMask",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|authInfo
|String array
|auth_info specifies additional conditions for the user command. The auth_info option string has to be given as name=value pair. For multiple conditions the -x option could be supplied multiple times.
Possible names for the auth_info are:
service
The service for which the userdb lookup should be tested. The value may be the name of a service, commonly used with Dovecot. For example: imap, pop3 or smtp.
lip
The local IP address (server) for the test.
rip
The remote IP address (client) for the test.
lport
The local port, e.g. 143
rport
The remote port, e.g. 24567
|sevice=imap
|-
|field
|String
|fetch only one specified field instead of all
|
|-
|expandField
|String
|expand configuration variable with user specific values
|
|-
|userdbOnly
|Boolean
|only fetch from userdb lookup and don’t process passdb
|
|-
|userMask
|String array
|search filter
|
|}

example:

<nowiki>
[
[
"user",
{
"userMask": [
"samik"
]
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["user",{"userMask":["samik"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
{
"samik": {
"gid": "1000",
"home": "/var/vmail/samik",
"junkflag": "0",
"mail": "Maildir:/mails/mails/samik/Maildir",
"namespace/Junk/hidden": "no",
"namespace/Junk/list": "yes",
"uid": "1000"
}
},
"bb"
]
]

CLI: doveadm user samik
</nowiki>

== doveadm mailbox ==
=== doveadm mailbox metadata set ===

set user mailbox metadata

parameters:

<nowiki>
{
"command": "mailboxMetadataSet",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "key",
"type": "string"
},
{
"name": "value",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata set
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to set
|
|-
|value
|String
|metadata value to set
|
|}

example:

<nowiki>
[
[
"mailboxMetadataSet",
{
"key": "/private/comment",
"mailbox": "INBOX",
"user": "samik",
"value": "test"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataSet",{"user":"samik","mailbox":"INBOX","key":"/private/comment","value":"test"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox metadata set –u samik INBOX /private/comment test
</nowiki>

=== doveadm mailbox metadata unset ===

unset user mailbox metadata

parameters:

<nowiki>
{
"command": "mailboxMetadataUnset",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata unset
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to unset
|
|}

example:

<nowiki>
[
[
"mailboxMetadataUnset",
{
"key": "/private/comment",
"mailbox": "INBOX",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataUnset",{"user":"samik","mailbox":"INBOX","key":"/private/comment"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox metadata unset –u samik INBOX /private/comment
</nowiki>

=== doveadm mailbox metadata get ===

get user mailbox metadata

parameters:

<nowiki>
{
"command": "mailboxMetadataGet",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata get
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to get
|
|}

example:

<nowiki>
[
[
"mailboxMetadataGet",
{
"key": "/private/comment",
"mailbox": "INBOX",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataGet",{"user":"samik","mailbox":"INBOX","key":"/private/comment"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response

<nowiki>
[
[
"doveadmResponse",
[
{
"value": "plaa"
}
],
"bb"
]
]

CLI: doveadm mailbox metadata get –u samik INBOX /private/comment
</nowiki>

=== doveadm mailbox list ===

list user mailbox metadata for a folder

parameters:

<nowiki>

"command": "mailboxMetadataList",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "keyPrefix",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata get
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to get
|
|-
|keyPrefix
|String
|search prefix for keys
|
|-
|mailbox
|String
|mailbox to fetch metadata from
|
|}

example:

<nowiki>
[
[
"mailboxMetadataList",
{
"mailbox": "INBOX",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataList",{"user":"samik","mailbox":"INBOX"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"key": "comment"
},
{
"key": "specialuse"
}
],
"bb"
]
]

CLI: doveadm mailbox metadata list –u samik INBOX
</nowiki>

=== doveadm mailbox status ===

fetch user mailbox status

parameters:

<nowiki>
{
"command": "mailboxStatus",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "totalSum",
"type": "boolean"
},
{
"name": "field",
"type": "array"
},
{
"name": "mailboxMask",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply status fetch
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|totalSum
|boolean
|
|
|-
|field
|String array
|fields to fetch
|all
|-
|mailboxMask
|String array
|fetch status on given mailboxes
|
|}

example:

<nowiki>

[
[
"mailboxStatus",
{
"field": [
"all"
],
"mailboxMask": [
"INBOX",
"INBOX/*",
"*"
],
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxStatus",{"user":"samik","field":["all"],"mailboxMask":["INBOX","INBOX/*","*"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"guid": "21b588150b156558eb3500007afd792c",
"highestmodseq": "5",
"mailbox": "Junk",
"messages": "0",
"recent": "0",
"uidnext": "1",
"uidvalidity": "1483019529",
"unseen": "0",
"vsize": "0"
},
{
"guid": "21b588150b156558eb3500007afd792c",
"highestmodseq": "5",
"mailbox": "INBOX",
"messages": "0",
"recent": "0",
"uidnext": "1",
"uidvalidity": "1483019529",
"unseen": "0",
"vsize": "0"
}
],
"bb"
]
]

CLI: doveadm mailbox status –u samik all “*”
</nowiki>

=== doveadm mailbox list ===

fetch user folder list

parameters:

<nowiki>
{
"command": "mailboxList",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mutf7",
"type": "boolean"
},
{
"name": "utf8",
"type": "boolean"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "mailboxMask",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid to apply mailbox list
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|mutf7
|Boolean
|
|
|-
|utf8
|Boolean
|fetch only certain fields instead of all
|
|-
|subscription
|Boolean
|
|
|-
|mailboxMask
|String array
|fetch list of given mailboxes
|
|}

example:

<nowiki>
[
[
"mailboxList",
{
"user": "samik"
},
"bb"
]
]
# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxList",{"user":"samik"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"mailbox": "Junk"
},
{
"mailbox": "INBOX"
}
],
"bb"
]
]

CLI: doveadm mailbox list –u samik
</nowiki>

=== doveadm mailbox create ===
create mailbox folder for user

parameters:

<nowiki>
{
"command": "mailboxCreate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "guid",
"type": "string"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply mailbox create
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|subscription
|Boolean
|
|
|-
|mailbox
|String array
|list of mailbox folders to create
|
|}

example:

<nowiki>
[
[
"mailboxCreate",
{
"mailbox": [
"INBOX/myfolder"
],
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxCreate",{"user":"samik","mailbox":["INBOX/myfolder"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>

[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox create –u samik INBOX/myfolder
</nowiki>

=== doveadm mailbox delete ===

delete user mailbox folder

parameters:

<nowiki>
{
"command": "mailboxDelete",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "requireEmpty",
"type": "boolean"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "recursive",
"type": "boolean"
},
{
"name": "unsafe",
"type": "boolean"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply delete
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|requireEmpty
|Boolean
|only delete if folder is empty
|
|-
|subscription
|Boolean
|
|
|-
|recursive
|Boolean
|delete also subfolders
|
|-
|unsafe
|Boolean
|
|
|-
|mailbox
|String array
|list of mailbox folders to create
|
|}

example:

<nowiki>
[
[
"mailboxDelete",
{
"mailbox": [
"INBOX/myfolder"
],
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxDelete",{"user":"samik","mailbox":["INBOX/myfolder"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox delete –u samik INBOX/myfolder
</nowiki>

=== doveadm mailbox rename ===

rename user folder

parameters:

<nowiki>
{
"command": "mailboxRename",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "newName",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply mailbox rename
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|subscriptions
|Boolean
|
|
|-
|newName
|String
|mailbox new name
|
|-
|mailbox
|String
|mailbox to rename
|
|}

example:

<nowiki>
[
[
"mailboxRename",
{
"mailbox": "INBOX/myfolder",
"newName": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxRename",{"user":"samik","mailbox":"INBOX/myfolder","newName":"INBOX/myfoldertoo"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox rename –u samik INBOX/myfolder INBOX/myfoldertoo
</nowiki>

=== doveadm mailbox subscribe ===

subscribe user to a mailbox

parameters:

<nowiki>
{
"command": "mailboxSubscribe",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply subscribe
|
|-
|userFile
|String
|optionally fetch usernames from. One username per line
|
|-
|mailbox
|String
|mailbox to subscribe
|
|}

example:

<nowiki>
[
[
"mailboxSubscribe",
{
"mailbox": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxSubscribe",{"user":"samik","mailbox":"INBOX/myfoldertoo"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:
<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox subscribe –u samik INBOX/myfoldertoo
</nowiki>

=== doveadm mailbox unsubscribe ===

unsubscribe user from an folder

parameters:

<nowiki>
{
"command": "mailboxUnsubscribe",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply unsubscribe
|
|-
|userFile
|String
|optionally fetch usernames from. One username per line
|
|-
|mailbox
|String
|mailbox to unsubscribe
|
|}

example:

<nowiki>
[
[
"mailboxUnsubscribe",
{
"mailbox": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxUnsubscribe",{"user":"samik","mailbox":"INBOX/myfoldertoo"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox unsubscribe –u samik INBOX/myfoldertoo
</nowiki>

=== doveadm mailbox update ===

update user mailbox information

parameters:

<nowiki>
{
"command": "mailboxUpdate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailboxGuid",
"type": "string"
},
{
"name": "uidValidity",
"type": "string"
},
{
"name": "minNextUid",
"type": "string"
},
{
"name": "minFirstRecentUid",
"type": "string"
},
{
"name": "minHighestModseq",
"type": "string"
},
{
"name": "minHighestPvtModseq",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply update
|
|-
|userFile
|String
|optionally fetch usernames from. One username per line
|
|-
|mailbox
|String
|mailbox to unsubscribe
|
|-
|mailboxGuid
|String
|set mailbox guid
|
|-
|uidValidity
|String
|set mailbox uidvalidity
|
|-
|minNextuid
|String
|set mailbox minimum next uid
|
|-
|minFirstRecentuid
|String
|set mailbox minimum recent uid
|
|-
|minHighestModseq
|String
|
|
|-
|minHighestPvtModseq
|String
|
|
|}

=== doveadm mailbox save ===

save mail into users mailbox

parameters:

<nowiki>
{
"command": "save",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "file",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to save mail into
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|mailbox
|String
|mailbox to unsubscribe
|
|-
|file
|String
|mail to inject
|
|}

example:

<nowiki>
[
[
"save",
{
"file": "From: Joulu Pukki <joulu.pukki@korvatunturi.fi>\nSubject: plaa\n\nmail body\n",
"mailbox": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["save",{"user":"samik","mailbox":"INBOX/myfoldertoo","file":"From: Joulu Pukki <joulu.pukki@korvatunturi.fi>\nSubject: plaa\n\nmail body\n"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]
</nowiki>

== doveadm fetch ==

fetch data from user mailbox

parameters:

<nowiki>
{
"command": "fetch",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "field",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to fetch data
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|field
|String array
|fields to fetch. Supported fields as of dovecot 2.2.26: hdr.<name> body.<section> binary.<section> user mailbox mailbox-guid seq uid guid flags modseq hdr body body.snippet text text.utf8 size.physical size.virtual date.received date.sent date.saved date.received.unixtime date.sent.unixtime date.saved.unixtime imap.envelope imap.body imap.bodystructure pop3.uidl pop3.order refcount storageid
|
|-
|query
|String array
|search query to user
|
|}

example:

<nowiki>
[
[
"fetch",
{
"field": [
"text"
],
"query": [
"mailbox",
"INBOX/myfoldertoo"
],
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["fetch",{"user":"samik","field":["text"],"query":["mailbox","INBOX/myfoldertoo"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"text": "From: Joulu Pukki <joulu.pukki@korvatunturi.fi>\nSubject: plaa\n\nmail body\n"
}
],
"bb"
]
]

CLI: doveadm fetch –u samik “text” mailbox INBOX/myfoldertoo
</nowiki>

== doveadm index ==

index user mailbox folder or folders

parameters:

<nowiki>
{
"command": "index",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "queue",
"type": "boolean"
},
{
"name": "maxRecent",
"type": "string"
},
{
"name": "mailboxMask",
"type": "string"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to index
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|query
|Boolean
|max number of recent mails to index
|
|-
|maxRecent
|String
|max number of recent mails to index
|
|-
|mailboxMask
|String
|mailbox search mask to apply indexing into
|
|}

example:

<nowiki>
[
[
"index",
{
"mailboxMask": "INBOX*",
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["index",{"user":"samik","mailboxMask":"INBOX*"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm index –u samik “INBOX*”
</nowiki>

== doveadm altmove ==

move mails between primary and alternative mailbox storage locations. Applicable to mdbox and sdbox mailbox formats only

parameters:

<nowiki>
{
"command": "altmove",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "reverse",
"type": "boolean"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to apply move
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|reverse
|Boolean
|search query to apply to mail move
|
|-
|query
|String array
|search query to apply to mail move
|
|}

example:

<nowiki>
[
[
"altmove",
{
"query": [
"mailbox",
"INBOX/myfoldertoo",
"savedbefore",
"since",
"30d"
],
"reverse": 0,
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["altmove",{"user":"samik","reverse":0,"query":["mailbox","INBOX/myfoldertoo","savedbefore","since","30d"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

== doveadm deduplicate ==

This command is used to expunge duplicated messages in mailboxes

parameters:

<nowiki>
{
"command": "deduplicate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "byMsgid",
"type": "boolean"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to deduplicate
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|byMsgId
|Boolean
|deduplicate by Message-ID instead of guid
|
|-
|query
|String array
|search query to apply to deduplicate
|
|}

== doveadm expunge ==

Expunge messages matching given search query

parameters:

<nowiki>
{
"command": "expunge",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "deleteEmptyMailbox",
"type": "boolean"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to expunge
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|deleteEmptyMailbox
|Boolean
|delete also mailbox if it’s empty after expunge has been applied
|
|-
|query
|String array
|search query to apply to expunge
|
|}

== doveadm flags ==
add, remove or replace messages' flags

=== doveadm flags add ===

add flag to a message or messages

parameters:

<nowiki>
{
"command": "flagsAdd",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "flag",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to add flags
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|flag
|String array
|list of flags to add
|
|-
|query
|String array
|search query to apply to flag add
|
|}

=== doveadm flags remove ===

remove flags from message or messages

parameters:

<nowiki>
{
"command": "flagsRemove",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "flag",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to add flags
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|flag
|String array
|list of flags to remove
|
|-
|query
|String array
|search query to apply to flag remove
|
|}

=== doveadm flags replace ===

Replace flags with another flag in message or messages. Replaces all current flags with the ones in the parameter list

parameters:

<nowiki>
{
"command": "flagsReplace",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "flag",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to replace flags
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|flag
|String array
|list of flags to replace with
|
|-
|query
|String array
|search query to apply to flag replace
|
|}

== doveadm import ==

Import messages matching given search query

parameters:

<nowiki>
{
"command": "import",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "subscribe",
"type": "boolean"
},
{
"name": "sourceLocation",
"type": "string"
},
{
"name": "destParentMailbox",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to apply import
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|subscribe
|boolean
|when enabled possible newly created folders are also subscibed
|
|-
|sourceLocation
|String
|location of source mailboxes
|
|-
|destParentMailbox
|String
|destination parent mailbox where to import
|
|-
|query
|String array
|search query for messages to import
|
|}

== doveadm force-resync ==

Under certain circumstances it may happen, that dovecot is unable to automatically solve problems with mailboxes. In such situations the force-resync command may be helpful. It tries to fix all problems. For sdbox and mdbox mailboxes the storage files will be also checked.

parameters:

<nowiki>
{
"command": "forceResync",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailboxMask",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|user
|String
|uid of user to apply resync
|
|-
|mailboxMask
|String
|apply forced resync on given mailboxes
|INBOX*
|}

example:

<nowiki>
[
[
"forceResync",
{
"mailboxMask": "INBOX*",
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["forceResync",{"user":"samik","mailboxMask":"INBOX*"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm force-resync –u samik “INBOX*”
</nowiki>

== doveadm purge ==

Remove messages with refcount=0 from mdbox files

parameters:

<nowiki>
{
"command": "purge",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to apply purge
|
|}

== doveadm search ==

Show a list of mailbox GUIDs and message UIDs matching given search query

parameters:

<nowiki>
{
"command": "search",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|user
|String
|uid of user to apply purge
|
|-
|query
|String array
|search query
|
|}

example:

<nowiki>
[
[
"search",
{
"query": [
"mailbox",
"INBOX*",
"all"
],
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["search",{"user":"samik","query":["mailbox","INBOX*","all"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"mailbox-guid": "cf497f128caf7c58612200007afd792c",
"uid": "1"
}
],
"bb"
]
]

CLI: doveadm search –u samik mailbox “INBOX*” all
</nowiki>

== doveadm copy ==

Copy messages matching the given search query into another mailbox

parameters:

<nowiki>
{
"command": "copy",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "destinationMailbox",
"type": "string"
},
{
"name": "sourceType",
"type": "string"
},
{
"name": "sourceUser",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm move ==

Move messages matching the given search query into another mailbox

parameters:

<nowiki>
{
"command": "move",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "destinationMailbox",
"type": "string"
},
{
"name": "sourceType",
"type": "string"
},
{
"name": "sourceUser",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm fscache rescan ==

force fscache rescan

parameters:

<nowiki>
{
"command": "fscacheRescan",
"parameters": [
{
"name": "path",
"type": "string"
},
{
"name": "maxAge",
"type": "integer"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm metacache ==
=== doveadm metacache clean ===

clean metacache content for given user or all users

parameters:

<nowiki>
{

"command": "metacacheClean",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "days",
"type": "integer"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache flush ===

flush metacache contents to storage for given user or all users

parameters:

<nowiki>
{
"command": "metacacheFlush",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache unpack ===

unpack metacache index bundle to target directory

parameters:

<nowiki>
{
"command": "metacacheUnpack",
"parameters": [
{
"name": "bundleName",
"type": "string"
},
{
"name": "bundle",
"type": "string"
},
{
"name": "destinationDirectory",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache flushall ===

flush metacache to storage for all users

parameters:

<nowiki>
{
"command": "metacacheFlushall",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache remove ===

remove metacache for given mask

parameters:

<nowiki>
{
"command": "metacacheRemove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "mask",
"type": "string"
}
]
}
</nowiki>
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache list ===

list local metacache contents

parameters:

<nowiki>
{
"command": "metacacheList",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm obox user delete ==

delete user data from storage, Cassandra and local caches (metacache and fscache).

parameters:

<nowiki>
{
"command": "oboxUserDelete",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

example:

<nowiki>
[
[
"oboxUserDelete",
{
"allUsers": 0,
"socketPath": "",
"user": "testuser003",
"userFile": ""
},
"aa"
]
]

# curl -v -u doveadm:hellodoveadm -X POST http://localhost:ype: application/json" -d '[["oboxUserDelete", {"allUsers":0,"user":"testuser003"}, "aa"]]'
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"aa"
]
]

CLI: doveadm obox user delete –u testuser003
</nowiki>

== doveadm sieve ==

Commands related to handling Sieve scripts.

=== doveadm sieve list ===

list user sieve scripts

parameters:

<nowiki>
{
"command": "sieveList",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve get ===

get user sieve script

parameters:

<nowiki>
{
"command": "sieveGet",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "scriptname",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve put ===

inject sieve script to user

parameters:

<nowiki>
{
"command": "sievePut",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "activate",
"type": "boolean"
},
{
"name": "scriptname",
"type": "string"
},
{
"name": "file",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve delete ===

delete user sieve

parameters:

<nowiki>
{
"command": "sieveDelete",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "ignoreActive",
"type": "boolean"
},
{
"name": "scriptname",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve activate ===

activate user sieve script

parameters:

<nowiki>
{
"command": "sieveActivate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "scriptname",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve deactivate ===

deactivate user sieve

parameters:

<nowiki>
{
"command": "sieveDeactivate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve rename ===

rename user sieve script

parameters:

<nowiki>
{
"command": "sieveRename",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "oldname",
"type": "string"
},
{
"name": "newname",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm fts ==
Dovecot fts indexing commands.

=== doveadm fts lookup ===

query user fts indexed data

parameters:

<nowiki>
{
"command": "ftsLookup",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts expand ===

<nowiki>
{
"command": "ftsExpand",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts tokenize ===

<nowiki>
{
"command": "ftsTokenize",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "language",
"type": "string"
},
{
"name": "text",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts optimize ===

<nowiki>
{
"command": "ftsOptimize",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts rescan ===

<nowiki>
{
"command": "ftsRescan",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

Template:DoveadmHTTPapi

2017-03-15T12:17:07Z

Oskarikentta: /* doveadm fs copy */

== Table of Contents ==
__TOC__

== 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:

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

=== 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:

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

Basic auth usage:
<nowiki>
curl -H "Authorization: Basic <base64 doveadm:doveadm_password>"
http://host:port/doveadm/v1
</nowiki>
or by letting curl to form the base64 encoded authentication basig authentication header:

<nowiki>
curl –u doveadm:password http://host:port/doveadm/v1
</nowiki>

=== 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:

<nowiki>

[
[
"command1",
{
"parameter1": "value",
"parameter2": "value",
"parameter3": "value"
},
"identifier"
]
]
</nowiki>
Multiple commands can be submitted in one json payload:
<nowiki>
[
[
"command1",
{
"parameter1": "value",
"parameter2": "value"
},
"identifier1"
],
[
"command2",
{
"parameter1": "value",
"parameter2": "value"
},
"identifier2"
]
]
</nowiki>

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:

<nowiki>

son payload:

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

</nowiki>

submitting the command with curl:

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

command line equivalent

doveadm reload

=== successful response ===

<nowiki>

[
[
"doveadmResponse",
[],
"a2"
]
]
</nowiki>

=== failure response ===

<nowiki>

[
[
"error",
{
"exitCode": 68,
"type": "exitCode"
},
"a2"
]
</nowiki>

=== failure codes ===

{| class="wikitable"
|-
|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
|}

== Supported commands ==

== doveadm service ==
=== doveadm service stop ===

stop one or more dovecot services on target host

<nowiki>
{
"command": "serviceStop",
"parameters": [
{
"name": "service",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|service
|string array
|Name of service to stop
|[“imap”,”imap-hibernate”]
|}

example:

<nowiki>
[
[
"serviceStop",
{
"service": [
"imap",
"imap-hibernate"
]
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["serviceStop",{"service":["imap","imap-hibernate"]},"aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm service stop imap imap-hibernate
</nowiki>

=== doveadm stop ===

stop dovecot on the target host
<nowiki>

{
"command": "stop",
"parameters": []
}

no parameters
</nowiki>
example:
<nowiki>
[
[
"stop",
{},
"a1"
]
]

# curl -u doveadm:hellodoveadm -X POST http://localhost:8080/doveadm/v1 -H "Content-Type: application/json" -d '[["stop",{},"a1"]]'

CLI: doveadm stop
</nowiki>

=== doveadm reload ===

reload dovecot configuration

<nowiki>
{
"command": "reload",
"parameters": []
}
</nowiki>

example:

<nowiki>
[
[
"reload",
{},
"a2"
]
]

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

CLI: doveadm reload
</nowiki>

== doveadm stats ==
=== doveadm stats dump ===

dump collected dovecot statistics

<nowiki>
{
"command": "statsDump",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "type",
"type": "string"
},
{
"name": "filter",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|+parameters
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|type
|String
|Type of stats to dump
|global
|-
|filter
|String
|Dump filter
|last_update 1483101542
|}

Example:

<nowiki>
[
[
"statsDump",
{
"type": "global"
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["statsDump",{"type":"global"},"aa"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"auth_cache_hits": "0",
"auth_cache_misses": "0",
"auth_db_tempfails": "0",
"auth_failures": "0",
"auth_master_successes": "0",
"auth_successes": "0",
"clock_time": "0.0",
"disk_input": "0",
"disk_output": "0",
"fscache_read": "0",
"fscache_stat": "0",
"fscache_write": "0",
"idx_del": "0",
"idx_iter": "0",
"idx_read": "0",
"idx_read_usecs": "0",
"idx_wbytes": "0",
"idx_write": "0",
"idx_write_usecs": "0",
"invol_cs": "0",
"last_update": "0.000000",
"mail_cache_hits": "0",
"mail_lookup_attr": "0",
"mail_lookup_path": "0",
"mail_read_bytes": "0",
"mail_read_count": "0",
"maj_faults": "0",
"min_faults": "0",
"num_cmds": "0",
"num_connected_sessions": "0",
"num_logins": "0",
"obox_copy": "0",
"obox_del": "0",
"obox_iter": "0",
"obox_read": "0",
"obox_read_usecs": "0",
"obox_stat": "0",
"obox_wbytes": "0",
"obox_write": "0",
"obox_write_usecs": "0",
"read_bytes": "0",
"read_count": "0",
"reset_timestamp": "1483104199",
"sys_cpu": "0.0",
"user_cpu": "0.0",
"vol_cs": "0",
"write_bytes": "0",
"write_count": "0"
}
],
"aa"
]
]

CLI: doveadm stats dump global
</nowiki>

=== doveadm stats reset ===
reset dovecot statistics counters
<nowiki>

{
"command": "statsReset",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|}

example:

<nowiki>
[
[
"statsReset",
{},
"aa"
]
]

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

CLI: doveadm stats reset
</nowiki>

== doveadm penalty ==

<nowiki>
show current penalties

{
"command": "penalty",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "netmask",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|string
|Path to doveadm socket
|/var/run/dovecot-server
|-
|netmask
|string
|To reduce/filter the output supply an IP address or a network range in CIDR notation (ip/mask)
|10.0.0.0/24
|}

example:

<nowiki>
[
[
"penalty",
{},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["penalty",{},"aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm penalty
</nowiki>

== doveadm kick ==

Kick user from dovecot. Applicable to session in dovecot backend only

<nowiki>
{
"command": "kick",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "force",
"type": "boolean"
},
{
"name": "mask",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|force
|Boolean
|Do a forced kick?
|0
|-
|mask
|String
|Uid mask
|testuser001
|}

example:

<nowiki>
[
[
"kick",
{
"force": 0,
"mask": "testuser001"
},
"aa"
]
]

# curl -v -u doveadm:hellodoveadm –H “Content-Type: application/json" -d '[["kick", {"mask":"testuser001"}, "aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm kick testuser001
</nowiki>

response for succesfull kick:

<nowiki>
[
[
"doveadmResponse",
[
{
"result": "testuser001"
}
],
"aa"
]
]
</nowiki>

response in case kick failed:

<nowiki>
[
[
"error",
{
"exitCode": 68,
"type": "exitCode"
},
"aa"
]
]
</nowiki>

== doveadm who ==

<nowiki>
list active dovecot sessions

{
"command": "who",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "separateConnections",
"type": "boolean"
},
{
"name": "mask",
"type": "array"
}
]
}
</nowiki>

parameters

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|string
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|separateConnections
|Boolean
|Show each user connection in separate entries
|0
|-
|mask
|string array
|Uid mask
|testuser001
|}

Example:

<nowiki>
[
[
"who",
{
"mask": "",
"separateConnections": 0,
"socketPath": ""
},
"aa"
]
]

# curl -v -u doveadm:hellodoveadm -X POST http://localhost:ype: application/json" -d '[["who", {}, "aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm who
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"connections": "1",
"ips": "(127.0.0.1)",
"pids": "(4999)",
"service": "imap",
"username": "testuser001"
}
],
"aa"
]
]
</nowiki>

== doveadm director ==
=== doveadm director status ===

Show backend statuses on directors. Available only in directors

<nowiki>
[
{
"command": "directorStatus",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "tag",
"type": "string"
}
]
}
]
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|String
|Show director status for Tagged hosts only
|NewBackend
|}

example:

<nowiki>
[
[
"directorStatus",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorStatus",{},"bb"]]' http://localhost:8080/doveadm/v1

</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"mail server ip": "10.0.0.234",
"state": "up",
"state-changed": "2016-12-15 08:31:37",
"tag": "",
"users": "1",
"vhosts": "100"
},
{
"mail server ip": "10.0.0.235",
"state": "up",
"state-changed": "2016-12-15 08:31:04",
"tag": "",
"users": "0",
"vhosts": "100"
}
],
"bb"
]
]

CLI: doveadm director status
</nowiki>

=== doveadm director map ===

list current user → host mappings. Applicable to director only

<nowiki>

"command": "directorMap",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "usersFile",
"type": "string"
},
{
"name": "hashMap",
"type": "boolean"
},
{
"name": "userMap",
"type": "boolean"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

parameters

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|usersFile
|String
|provide Path to users list. One username per line
|/etc/dovecot/userlist.txt
|-
|hashMap
|Boolean
|Output users as hashmap
|True
|-
|userMap
|Boolean
|Output users as userlist
|True
|-
|host
|String
|Show only mappings to given host
|10.0.0.234
|}

example:

<nowiki>
[
[
"directorMap",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorMap",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"expire time": "2016-12-30 14:52:56",
"hash": "3853430566",
"mail server ip": "10.0.0.235",
"user": "samik"
}
],
"bb"
]
]

CLI: doveadm director map
</nowiki>

=== doveadm director add ===

add backend to director ring

<nowiki>
{
"command": "directorAdd",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "tag",
"type": "string"
},
{
"name": "host",
"type": "string"
},
{
"name": "vhostCount",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|tag
|String
|apply tag to backend
|/etc/dovecot/userlist.txt
|-
|host
|String
|backend ip to add
|10.0.0.234
|-
|vhostCount
|String
|vhost count to add
|100
|}

Example:

<nowiki>
[
[
"directorAdd",
{
"host": "10.0.234"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorAdd",{"host":"10.0.234"},"bb"]]' http://localhost:8080/doveadm/v1

CLI: doveadm director add 10.0.0.234
</nowiki>

=== doveadm director update ===

<nowiki>
{
"command": "directorUpdate",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
},
{
"name": "vhostCount",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|string
|Show director status for tagged hosts only
|NewBackend
|}

=== doveadm director up ===

<nowiki>
{
"command": "directorUp",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|string
|Show director status for tagged hosts only
|NewBackend
|}

=== doveadm director down ===

<nowiki>
{
"command": "directorDown",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|string
|Show director status for tagged hosts only
|NewBackend
|}

=== doveadm director remove ===

remove backend from director ring

<nowiki>
{
"command": "directorRemove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|host
|String
|backend to remove
|10.0.0.134
|}

example:

<nowiki>
[
[
"directorRemove",
{
"host": "10.0.0.234"
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRemove",{"host":"10.0.0.234"},"aa"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"aa"
]
]

CLI: doveadm director remove 10.0.0.234
</nowiki>

=== doveadm director move ===

move user mapping from backend to another or create director mapping for an user
<nowiki>
{
"command": "directorMove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|user
|String
|User uid to move
|testuser001
|-
|host
|string
|Target backend ip as listed in doveadm doveadm director status
|10.0.0.234
|}

example:

<nowiki>
[
[
"directorMove",
{
"host": "10.0.234",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorMove",{"user":"samik","host":"10.0.234"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director move samik 10.0.0.234
</nowiki>

== doveadm director kick ==

<nowiki>
{
"command": "directorKick",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|user
|String
|uid of user to kick
|samik
|}

example:

<nowiki>
[
[
"directorKick",
{
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorKick",{"user":"samik"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director kick samik
</nowiki>

=== doveadm director flush ===

flush connection mappings to one backend at director level. All users mapped to given host will be flushed from the hashmap table and will be redistributed to backends.

Parameters:

<nowiki>
{
"command": "directorFlush",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "forceFlush",
"type": "boolean"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|forceFlush
|Boolean
|Flag to make flush forced
|True
|-
|host
|String
|Backend ip address from doveadm director status list
|10.0.0.234
|}

example:

<nowiki>
[
[
"directorFlush",
{
"host": "10.0.0.234"
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorFlush",{"host":"10.0.0.234"},"aa"]]' http://localhost:8080/doveadm/v1

</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"aa"
]
]
CLI: doveadm director flush 10.0.234
</nowiki>

=== doveadm director dump ===

Dumb the current director backend host configuration as commands

<nowiki>
{
"command": "directorDump",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|}

example:

<nowiki>
[
[
"directorDump",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorDump",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"command": "add",
"host": "10.0.0.234",
"socket-path": "/var/run/dovecot/director-admin",
"vhost_count": "100"
},
{
"command": "add",
"host": "10.0.0.235",
"socket-path": "/var/run/dovecot/director-admin",
"vhost_count": "100"
}
],
"bb"
]
]

CLI: doveadm director dump
</nowiki>

=== doveadm director ring add ===

add new director to director ring

parameters:

<nowiki>
{
"command": "directorRingAdd",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "ip",
"type": "string"
},
{
"name": "port",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|ip
|String
|director ip address to add
|10.0.0.233
|-
|port
|String
|port number to use if not default
|9143
|}

example:

<nowiki>
[
[
"directorRingAdd",
{
"ip": "10.0.0.233"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRingAdd",{"ip":"10.0.0.233"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director ring add 10.0.0.233
</nowiki>

=== doveadm director ring remove ===

remove director from director ring

parameters:

<nowiki>
{
"command": "directorRingRemove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "ip",
"type": "string"
},
{
"name": "port",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|ip
|String
|director ip to remove
|10.0.0.233
|-
|port
|String
|director service port if not default
|9143
|}

example:

<nowiki>
[
[
"directorRingRemove",
{
"ip": "10.0.0.233"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRingRemove",{"ip":"10.0.0.233"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director ring remove 10.0.0.233
</nowiki>

=== doveadm director ring status ===

show director ring status

parameters:

<nowiki>

{
"command": "directorRingStatus",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|}

example:

<nowiki>
[
[
"directorRingStatus",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRingStatus",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>

[
"doveadmResponse",
[
{
"director ip": "10.0.0.232",
"last failed": "never",
"port": "9143",
"status": "synced",
"type": "self"
},
{
"director ip": "10.0.0.233",
"last failed": "never",
"port": "9143",
"status": "",
"type": ""
}
],
"bb"
]
]

CLI: doveadm director ring status
</nowiki>

== doveadm proxy ==

The doveadm proxy commands are used to list or kick active Dovecot proxy connections.

=== doveadm proxy list ===

list active connections in the dovecot proxy

parameters:

<nowiki>
{
"command": "proxyList",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|}

example:

<nowiki>
[
[
"proxyList",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["proxyList",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"dest-ip": "127.0.0.1",
"dest-port": "1143",
"service": "imap",
"src-ip": "10.0.0.153",
"username": "samik"
}
],
"bb"
]
]

CLI: doveadm proxy list
</nowiki>

=== doveadm proxy kick ===

kick user session from proxy. applicable to imap/pop3/managesieve sessions

parameters:

<nowiki>
{
"command": "proxyKick",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|userid to kick
|samik
|}

example:

<nowiki>
[
[
"proxyKick",
{
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["proxyKick",{"user":"samik"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"count": "1"
}
],
"bb"
]
]

CLI: doveadm proxy kick samik
</nowiki>

== doveadm logs errors ==

fetch errors log

paraments:

<nowiki>
{
"command": "logErrors",
"parameters": [
{
"name": "since",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|}

example:

<nowiki>
[
[
"logErrors",
{},
"a2"
]
]

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

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"prefix": "stats",
"text": "Stats client input error: Invalid level",
"timestamp": "Dec 09 16:24:00",
"type": "Error"
},
{
"prefix": "doveadm(127.0.0.1)",
"text": "read(/var/run/dovecot/stats) unexpectedly disconnected",
"timestamp": "Dec 09 16:24:00",
"type": "Fatal"
},
{
"prefix": "stats",
"text": "Stats client input error: Invalid level",
"timestamp": "Dec 09 16:24:22",
"type": "Error"
},
{
"prefix": "stats",
"text": "Stats client input error: Invalid level",
"timestamp": "Dec 09 16:27:48",
"type": "Error"
},
{
"prefix": "director",
"text": "Empty server list",
"timestamp": "Dec 09 16:29:13",
"type": "Error"
},
{
"prefix": "director",
"text": "Invalid value for director_mail_servers setting",
"timestamp": "Dec 09 16:29:13",
"type": "Fatal"
}
],
"a2"
]
]

CLI: doveadm log errors
</nowiki>

== doveadm dict ==
=== doveadm dict get ===

get user key value from configured dictionary

parameters:

<nowiki>
{
"command": "dictGet",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to query
|samik
|-
|dictUri
|String
|optional URI for dictionary to query
|
|-
|key
|String
|key to query
|
|}

=== doveadm dict set ===

set user key value in configured dictionary

parameters:

<nowiki>
{
"command": "dictSet",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
},
{
"name": "value",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|samik
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|key
|String
|dictionary key to modify
|
|-
|value
|string
|value to set
|
|}

=== doveadm dict unset ===

unset user key value in configured dictionary

parameters:

<nowiki>
{
"command": "dictUnset",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|key
|String
|dictionary key to unset
|
|}
== doveadm dict inc ==

increase users key value in dictionary

parameters:

<nowiki>
{
"command": "dictInc",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
},
{
"name": "difference",
"type": "integer"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|-
|key
|String
|dictionary key to increase
|
|-
|difference
|integer
|increment value
|
|}

=== doveadm dict iter ===

list user keys in dictionary

parameters:

<nowiki>
{
"command": "dictIter",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "exact",
"type": "boolean"
},
{
"name": "recurse",
"type": "boolean"
},
{
"name": "noValue",
"type": "boolean"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "prefix",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|exact
|Boolean
|list only exact matches
|
|-
|recurce
|Boolean
|do recursive search
|
|-
|noValue
|Boolean
|list also keys that have no value set
|
|-
|prefix
|String
|search only keys with given prefix
|
|}

== doveadm fs ==
=== doveadm fs get ===

get object from storage

parameters:

<nowiki>
{
"command": "fsGet",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem to fetch
|
|}

=== doveadm fs put ===

put object to storage

parameters:

<nowiki>
{
"command": "fsPut",
"parameters": [
{
"name": "hash",
"type": "string"
},
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "inputPath",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|hash
|string
|
|
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|inputPath
|String
|source object path in local filesystem
|
|-
|path
|String
|object path filesystem to put
|
|}

=== doveadm fs copy ===

copy object in storage

parameters:

<nowiki>
{
"command": "fsCopy",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "sourcePath",
"type": "string"
},
{
"name": "destinationPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|sourcePath
|String
|source object path
|
|-
|Destination path
|String
|destination object path in filesystem
|
|}

=== doveadm fs stat ===

fetch fs driver statistics

parameters:

<nowiki>
{
"command": "fsStat",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem fetch statistics for
|
|}

=== doveadm fs metadata ===

get filesystem object metadata

parameters:

<nowiki>
{
"command": "fsMetadata",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem fetch statistics for
|
|}

=== doveadm fs delete ===

delete object from storage

<nowiki>
{
"command": "fsDelete",
"parameters": [
{
"name": "recursive",
"type": "boolean"
},
{
"name": "maxParallel",
"type": "integer"
},
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem fetch statistics for
|
|-
|recursive
|Boolean
|do a recursive delete of path
|
|-
|maxParallel
|integer
|max number of parallel workers
|
|}

=== doveadm fs iter ===

list objects in given fs path

parameters:

<nowiki>
{
"command": "fsIter",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|path in filesystem to list
|
|}

=== doveadm fs iter-dirs ===
ist subfolders in given path

parameters:

<nowiki>
{
"command": "fsIterDirs",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|path in filesystem to list for subfolders
|
|}

== doveadm auth cache flush ==

flush authentication cache for one user or all users

parameters:

<nowiki>
{
"command": "authCacheFlush",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String array
|optional list of users in flush
|[“samik”,”samitest”]
|}

example:

<nowiki>
[
[
"authCacheFlush",
{
"user": [
"samik"
]
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["authCacheFlush",{"user":["samik"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"entries": "0"
}
],
"bb"
]
]

CLI: doveadm auth cache flush samik
</nowiki>

== doveadm user ==

do a userdb lookup for an user

<nowiki>
{
"command": "user",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "authInfo",
"type": "array"
},
{
"name": "field",
"type": "string"
},
{
"name": "expandField",
"type": "string"
},
{
"name": "userdbOnly",
"type": "boolean"
},
{
"name": "userMask",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|authInfo
|String array
|auth_info specifies additional conditions for the user command. The auth_info option string has to be given as name=value pair. For multiple conditions the -x option could be supplied multiple times.
Possible names for the auth_info are:
service
The service for which the userdb lookup should be tested. The value may be the name of a service, commonly used with Dovecot. For example: imap, pop3 or smtp.
lip
The local IP address (server) for the test.
rip
The remote IP address (client) for the test.
lport
The local port, e.g. 143
rport
The remote port, e.g. 24567
|sevice=imap
|-
|field
|String
|fetch only one specified field instead of all
|
|-
|expandField
|String
|expand configuration variable with user specific values
|
|-
|userdbOnly
|Boolean
|only fetch from userdb lookup and don’t process passdb
|
|-
|userMask
|String array
|search filter
|
|}

example:

<nowiki>
[
[
"user",
{
"userMask": [
"samik"
]
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["user",{"userMask":["samik"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
{
"samik": {
"gid": "1000",
"home": "/var/vmail/samik",
"junkflag": "0",
"mail": "Maildir:/mails/mails/samik/Maildir",
"namespace/Junk/hidden": "no",
"namespace/Junk/list": "yes",
"uid": "1000"
}
},
"bb"
]
]

CLI: doveadm user samik
</nowiki>

== doveadm mailbox ==
=== doveadm mailbox metadata set ===

set user mailbox metadata

parameters:

<nowiki>
{
"command": "mailboxMetadataSet",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "key",
"type": "string"
},
{
"name": "value",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata set
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to set
|
|-
|value
|String
|metadata value to set
|
|}

example:

<nowiki>
[
[
"mailboxMetadataSet",
{
"key": "/private/comment",
"mailbox": "INBOX",
"user": "samik",
"value": "test"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataSet",{"user":"samik","mailbox":"INBOX","key":"/private/comment","value":"test"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox metadata set –u samik INBOX /private/comment test
</nowiki>

=== doveadm mailbox metadata unset ===

unset user mailbox metadata

parameters:

<nowiki>
{
"command": "mailboxMetadataUnset",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata unset
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to unset
|
|}

example:

<nowiki>
[
[
"mailboxMetadataUnset",
{
"key": "/private/comment",
"mailbox": "INBOX",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataUnset",{"user":"samik","mailbox":"INBOX","key":"/private/comment"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox metadata unset –u samik INBOX /private/comment
</nowiki>

=== doveadm mailbox metadata get ===

get user mailbox metadata

parameters:

<nowiki>
{
"command": "mailboxMetadataGet",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata get
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to get
|
|}

example:

<nowiki>
[
[
"mailboxMetadataGet",
{
"key": "/private/comment",
"mailbox": "INBOX",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataGet",{"user":"samik","mailbox":"INBOX","key":"/private/comment"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response

<nowiki>
[
[
"doveadmResponse",
[
{
"value": "plaa"
}
],
"bb"
]
]

CLI: doveadm mailbox metadata get –u samik INBOX /private/comment
</nowiki>

=== doveadm mailbox list ===

list user mailbox metadata for a folder

parameters:

<nowiki>

"command": "mailboxMetadataList",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "keyPrefix",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata get
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to get
|
|-
|keyPrefix
|String
|search prefix for keys
|
|-
|mailbox
|String
|mailbox to fetch metadata from
|
|}

example:

<nowiki>
[
[
"mailboxMetadataList",
{
"mailbox": "INBOX",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataList",{"user":"samik","mailbox":"INBOX"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"key": "comment"
},
{
"key": "specialuse"
}
],
"bb"
]
]

CLI: doveadm mailbox metadata list –u samik INBOX
</nowiki>

=== doveadm mailbox status ===

fetch user mailbox status

parameters:

<nowiki>
{
"command": "mailboxStatus",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "totalSum",
"type": "boolean"
},
{
"name": "field",
"type": "array"
},
{
"name": "mailboxMask",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply status fetch
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|totalSum
|boolean
|
|
|-
|field
|String array
|fields to fetch
|all
|-
|mailboxMask
|String array
|fetch status on given mailboxes
|
|}

example:

<nowiki>

[
[
"mailboxStatus",
{
"field": [
"all"
],
"mailboxMask": [
"INBOX",
"INBOX/*",
"*"
],
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxStatus",{"user":"samik","field":["all"],"mailboxMask":["INBOX","INBOX/*","*"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"guid": "21b588150b156558eb3500007afd792c",
"highestmodseq": "5",
"mailbox": "Junk",
"messages": "0",
"recent": "0",
"uidnext": "1",
"uidvalidity": "1483019529",
"unseen": "0",
"vsize": "0"
},
{
"guid": "21b588150b156558eb3500007afd792c",
"highestmodseq": "5",
"mailbox": "INBOX",
"messages": "0",
"recent": "0",
"uidnext": "1",
"uidvalidity": "1483019529",
"unseen": "0",
"vsize": "0"
}
],
"bb"
]
]

CLI: doveadm mailbox status –u samik all “*”
</nowiki>

=== doveadm mailbox list ===

fetch user folder list

parameters:

<nowiki>
{
"command": "mailboxList",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mutf7",
"type": "boolean"
},
{
"name": "utf8",
"type": "boolean"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "mailboxMask",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid to apply mailbox list
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|mutf7
|Boolean
|
|
|-
|utf8
|Boolean
|fetch only certain fields instead of all
|
|-
|subscription
|Boolean
|
|
|-
|mailboxMask
|String array
|fetch list of given mailboxes
|
|}

example:

<nowiki>
[
[
"mailboxList",
{
"user": "samik"
},
"bb"
]
]
# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxList",{"user":"samik"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"mailbox": "Junk"
},
{
"mailbox": "INBOX"
}
],
"bb"
]
]

CLI: doveadm mailbox list –u samik
</nowiki>

=== doveadm mailbox create ===
create mailbox folder for user

parameters:

<nowiki>
{
"command": "mailboxCreate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "guid",
"type": "string"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply mailbox create
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|subscription
|Boolean
|
|
|-
|mailbox
|String array
|list of mailbox folders to create
|
|}

example:

<nowiki>
[
[
"mailboxCreate",
{
"mailbox": [
"INBOX/myfolder"
],
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxCreate",{"user":"samik","mailbox":["INBOX/myfolder"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>

[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox create –u samik INBOX/myfolder
</nowiki>

=== doveadm mailbox delete ===

delete user mailbox folder

parameters:

<nowiki>
{
"command": "mailboxDelete",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "requireEmpty",
"type": "boolean"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "recursive",
"type": "boolean"
},
{
"name": "unsafe",
"type": "boolean"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply delete
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|requireEmpty
|Boolean
|only delete if folder is empty
|
|-
|subscription
|Boolean
|
|
|-
|recursive
|Boolean
|delete also subfolders
|
|-
|unsafe
|Boolean
|
|
|-
|mailbox
|String array
|list of mailbox folders to create
|
|}

example:

<nowiki>
[
[
"mailboxDelete",
{
"mailbox": [
"INBOX/myfolder"
],
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxDelete",{"user":"samik","mailbox":["INBOX/myfolder"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox delete –u samik INBOX/myfolder
</nowiki>

=== doveadm mailbox rename ===

rename user folder

parameters:

<nowiki>
{
"command": "mailboxRename",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "newName",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply mailbox rename
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|subscriptions
|Boolean
|
|
|-
|newName
|String
|mailbox new name
|
|-
|mailbox
|String
|mailbox to rename
|
|}

example:

<nowiki>
[
[
"mailboxRename",
{
"mailbox": "INBOX/myfolder",
"newName": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxRename",{"user":"samik","mailbox":"INBOX/myfolder","newName":"INBOX/myfoldertoo"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox rename –u samik INBOX/myfolder INBOX/myfoldertoo
</nowiki>

=== doveadm mailbox subscribe ===

subscribe user to a mailbox

parameters:

<nowiki>
{
"command": "mailboxSubscribe",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply subscribe
|
|-
|userFile
|String
|optionally fetch usernames from. One username per line
|
|-
|mailbox
|String
|mailbox to subscribe
|
|}

example:

<nowiki>
[
[
"mailboxSubscribe",
{
"mailbox": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxSubscribe",{"user":"samik","mailbox":"INBOX/myfoldertoo"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:
<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox subscribe –u samik INBOX/myfoldertoo
</nowiki>

=== doveadm mailbox unsubscribe ===

unsubscribe user from an folder

parameters:

<nowiki>
{
"command": "mailboxUnsubscribe",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply unsubscribe
|
|-
|userFile
|String
|optionally fetch usernames from. One username per line
|
|-
|mailbox
|String
|mailbox to unsubscribe
|
|}

example:

<nowiki>
[
[
"mailboxUnsubscribe",
{
"mailbox": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxUnsubscribe",{"user":"samik","mailbox":"INBOX/myfoldertoo"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox unsubscribe –u samik INBOX/myfoldertoo
</nowiki>

=== doveadm mailbox update ===

update user mailbox information

parameters:

<nowiki>
{
"command": "mailboxUpdate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailboxGuid",
"type": "string"
},
{
"name": "uidValidity",
"type": "string"
},
{
"name": "minNextUid",
"type": "string"
},
{
"name": "minFirstRecentUid",
"type": "string"
},
{
"name": "minHighestModseq",
"type": "string"
},
{
"name": "minHighestPvtModseq",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply update
|
|-
|userFile
|String
|optionally fetch usernames from. One username per line
|
|-
|mailbox
|String
|mailbox to unsubscribe
|
|-
|mailboxGuid
|String
|set mailbox guid
|
|-
|uidValidity
|String
|set mailbox uidvalidity
|
|-
|minNextuid
|String
|set mailbox minimum next uid
|
|-
|minFirstRecentuid
|String
|set mailbox minimum recent uid
|
|-
|minHighestModseq
|String
|
|
|-
|minHighestPvtModseq
|String
|
|
|}

=== doveadm mailbox save ===

save mail into users mailbox

parameters:

<nowiki>
{
"command": "save",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "file",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to save mail into
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|mailbox
|String
|mailbox to unsubscribe
|
|-
|file
|String
|mail to inject
|
|}

example:

<nowiki>
[
[
"save",
{
"file": "From: Joulu Pukki <joulu.pukki@korvatunturi.fi>\nSubject: plaa\n\nmail body\n",
"mailbox": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["save",{"user":"samik","mailbox":"INBOX/myfoldertoo","file":"From: Joulu Pukki <joulu.pukki@korvatunturi.fi>\nSubject: plaa\n\nmail body\n"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]
</nowiki>

== doveadm fetch ==

fetch data from user mailbox

parameters:

<nowiki>
{
"command": "fetch",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "field",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to fetch data
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|field
|String array
|fields to fetch. Supported fields as of dovecot 2.2.26: hdr.<name> body.<section> binary.<section> user mailbox mailbox-guid seq uid guid flags modseq hdr body body.snippet text text.utf8 size.physical size.virtual date.received date.sent date.saved date.received.unixtime date.sent.unixtime date.saved.unixtime imap.envelope imap.body imap.bodystructure pop3.uidl pop3.order refcount storageid
|
|-
|query
|String array
|search query to user
|
|}

example:

<nowiki>
[
[
"fetch",
{
"field": [
"text"
],
"query": [
"mailbox",
"INBOX/myfoldertoo"
],
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["fetch",{"user":"samik","field":["text"],"query":["mailbox","INBOX/myfoldertoo"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"text": "From: Joulu Pukki <joulu.pukki@korvatunturi.fi>\nSubject: plaa\n\nmail body\n"
}
],
"bb"
]
]

CLI: doveadm fetch –u samik “text” mailbox INBOX/myfoldertoo
</nowiki>

== doveadm index ==

index user mailbox folder or folders

parameters:

<nowiki>
{
"command": "index",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "queue",
"type": "boolean"
},
{
"name": "maxRecent",
"type": "string"
},
{
"name": "mailboxMask",
"type": "string"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to index
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|query
|Boolean
|max number of recent mails to index
|
|-
|maxRecent
|String
|max number of recent mails to index
|
|-
|mailboxMask
|String
|mailbox search mask to apply indexing into
|
|}

example:

<nowiki>
[
[
"index",
{
"mailboxMask": "INBOX*",
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["index",{"user":"samik","mailboxMask":"INBOX*"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm index –u samik “INBOX*”
</nowiki>

== doveadm altmove ==

move mails between primary and alternative mailbox storage locations. Applicable to mdbox and sdbox mailbox formats only

parameters:

<nowiki>
{
"command": "altmove",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "reverse",
"type": "boolean"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to apply move
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|reverse
|Boolean
|search query to apply to mail move
|
|-
|query
|String array
|search query to apply to mail move
|
|}

example:

<nowiki>
[
[
"altmove",
{
"query": [
"mailbox",
"INBOX/myfoldertoo",
"savedbefore",
"since",
"30d"
],
"reverse": 0,
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["altmove",{"user":"samik","reverse":0,"query":["mailbox","INBOX/myfoldertoo","savedbefore","since","30d"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

== doveadm deduplicate ==

This command is used to expunge duplicated messages in mailboxes

parameters:

<nowiki>
{
"command": "deduplicate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "byMsgid",
"type": "boolean"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to deduplicate
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|byMsgId
|Boolean
|deduplicate by Message-ID instead of guid
|
|-
|query
|String array
|search query to apply to deduplicate
|
|}

== doveadm expunge ==

Expunge messages matching given search query

parameters:

<nowiki>
{
"command": "expunge",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "deleteEmptyMailbox",
"type": "boolean"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to expunge
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|deleteEmptyMailbox
|Boolean
|delete also mailbox if it’s empty after expunge has been applied
|
|-
|query
|String array
|search query to apply to expunge
|
|}

== doveadm flags ==
add, remove or replace messages' flags

=== doveadm flags add ===

add flag to a message or messages

parameters:

<nowiki>
{
"command": "flagsAdd",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "flag",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to add flags
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|flag
|String array
|list of flags to add
|
|-
|query
|String array
|search query to apply to flag add
|
|}

=== doveadm flags remove ===

remove flags from message or messages

parameters:

<nowiki>
{
"command": "flagsRemove",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "flag",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to add flags
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|flag
|String array
|list of flags to remove
|
|-
|query
|String array
|search query to apply to flag remove
|
|}

=== doveadm flags replace ===

Replace flags with another flag in message or messages. Replaces all current flags with the ones in the parameter list

parameters:

<nowiki>
{
"command": "flagsReplace",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "flag",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to replace flags
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|flag
|String array
|list of flags to replace with
|
|-
|query
|String array
|search query to apply to flag replace
|
|}

== doveadm import ==

Import messages matching given search query

parameters:

<nowiki>
{
"command": "import",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "subscribe",
"type": "boolean"
},
{
"name": "sourceLocation",
"type": "string"
},
{
"name": "destParentMailbox",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to apply import
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|subscribe
|boolean
|when enabled possible newly created folders are also subscibed
|
|-
|sourceLocation
|String
|location of source mailboxes
|
|-
|destParentMailbox
|String
|destination parent mailbox where to import
|
|-
|query
|String array
|search query for messages to import
|
|}

== doveadm force-resync ==

Under certain circumstances it may happen, that dovecot is unable to automatically solve problems with mailboxes. In such situations the force-resync command may be helpful. It tries to fix all problems. For sdbox and mdbox mailboxes the storage files will be also checked.

parameters:

<nowiki>
{
"command": "forceResync",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailboxMask",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|user
|String
|uid of user to apply resync
|
|-
|mailboxMask
|String
|apply forced resync on given mailboxes
|INBOX*
|}

example:

<nowiki>
[
[
"forceResync",
{
"mailboxMask": "INBOX*",
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["forceResync",{"user":"samik","mailboxMask":"INBOX*"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm force-resync –u samik “INBOX*”
</nowiki>

== doveadm purge ==

Remove messages with refcount=0 from mdbox files

parameters:

<nowiki>
{
"command": "purge",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to apply purge
|
|}

== doveadm search ==

Show a list of mailbox GUIDs and message UIDs matching given search query

parameters:

<nowiki>
{
"command": "search",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|user
|String
|uid of user to apply purge
|
|-
|query
|String array
|search query
|
|}

example:

<nowiki>
[
[
"search",
{
"query": [
"mailbox",
"INBOX*",
"all"
],
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["search",{"user":"samik","query":["mailbox","INBOX*","all"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"mailbox-guid": "cf497f128caf7c58612200007afd792c",
"uid": "1"
}
],
"bb"
]
]

CLI: doveadm search –u samik mailbox “INBOX*” all
</nowiki>

== doveadm copy ==

Copy messages matching the given search query into another mailbox

parameters:

<nowiki>
{
"command": "copy",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "destinationMailbox",
"type": "string"
},
{
"name": "sourceType",
"type": "string"
},
{
"name": "sourceUser",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm move ==

Move messages matching the given search query into another mailbox

parameters:

<nowiki>
{
"command": "move",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "destinationMailbox",
"type": "string"
},
{
"name": "sourceType",
"type": "string"
},
{
"name": "sourceUser",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm fscache rescan ==

force fscache rescan

parameters:

<nowiki>
{
"command": "fscacheRescan",
"parameters": [
{
"name": "path",
"type": "string"
},
{
"name": "maxAge",
"type": "integer"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm metacache ==
=== doveadm metacache clean ===

clean metacache content for given user or all users

parameters:

<nowiki>
{

"command": "metacacheClean",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "days",
"type": "integer"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache flush ===

flush metacache contents to storage for given user or all users

parameters:

<nowiki>
{
"command": "metacacheFlush",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache unpack ===

unpack metacache index bundle to target directory

parameters:

<nowiki>
{
"command": "metacacheUnpack",
"parameters": [
{
"name": "bundleName",
"type": "string"
},
{
"name": "bundle",
"type": "string"
},
{
"name": "destinationDirectory",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache flushall ===

flush metacache to storage for all users

parameters:

<nowiki>
{
"command": "metacacheFlushall",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache remove ===

remove metacache for given mask

parameters:

<nowiki>
{
"command": "metacacheRemove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "mask",
"type": "string"
}
]
}
</nowiki>
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache list ===

list local metacache contents

parameters:

<nowiki>
{
"command": "metacacheList",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm obox user delete ==

delete user data from storage, Cassandra and local caches (metacache and fscache).

parameters:

<nowiki>
{
"command": "oboxUserDelete",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

example:

<nowiki>
[
[
"oboxUserDelete",
{
"allUsers": 0,
"socketPath": "",
"user": "testuser003",
"userFile": ""
},
"aa"
]
]

# curl -v -u doveadm:hellodoveadm -X POST http://localhost:ype: application/json" -d '[["oboxUserDelete", {"allUsers":0,"user":"testuser003"}, "aa"]]'
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"aa"
]
]

CLI: doveadm obox user delete –u testuser003
</nowiki>

== doveadm sieve ==

Commands related to handling Sieve scripts.

=== doveadm sieve list ===

list user sieve scripts

parameters:

<nowiki>
{
"command": "sieveList",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve get ===

get user sieve script

parameters:

<nowiki>
{
"command": "sieveGet",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "scriptname",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve put ===

inject sieve script to user

parameters:

<nowiki>
{
"command": "sievePut",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "activate",
"type": "boolean"
},
{
"name": "scriptname",
"type": "string"
},
{
"name": "file",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve delete ===

delete user sieve

parameters:

<nowiki>
{
"command": "sieveDelete",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "ignoreActive",
"type": "boolean"
},
{
"name": "scriptname",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve activate ===

activate user sieve script

parameters:

<nowiki>
{
"command": "sieveActivate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "scriptname",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve deactivate ===

deactivate user sieve

parameters:

<nowiki>
{
"command": "sieveDeactivate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve rename ===

rename user sieve script

parameters:

<nowiki>
{
"command": "sieveRename",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "oldname",
"type": "string"
},
{
"name": "newname",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm fts ==
Dovecot fts indexing commands.

=== doveadm fts lookup ===

query user fts indexed data

parameters:

<nowiki>
{
"command": "ftsLookup",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts expand ===

<nowiki>
{
"command": "ftsExpand",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts tokenize ===

<nowiki>
{
"command": "ftsTokenize",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "language",
"type": "string"
},
{
"name": "text",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts optimize ===

<nowiki>
{
"command": "ftsOptimize",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts rescan ===

<nowiki>
{
"command": "ftsRescan",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

Template:DoveadmHTTPapi

2017-03-15T12:12:48Z

Oskarikentta: /* doveadm dict inc */

== Table of Contents ==
__TOC__

== 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:

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

=== 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:

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

Basic auth usage:
<nowiki>
curl -H "Authorization: Basic <base64 doveadm:doveadm_password>"
http://host:port/doveadm/v1
</nowiki>
or by letting curl to form the base64 encoded authentication basig authentication header:

<nowiki>
curl –u doveadm:password http://host:port/doveadm/v1
</nowiki>

=== 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:

<nowiki>

[
[
"command1",
{
"parameter1": "value",
"parameter2": "value",
"parameter3": "value"
},
"identifier"
]
]
</nowiki>
Multiple commands can be submitted in one json payload:
<nowiki>
[
[
"command1",
{
"parameter1": "value",
"parameter2": "value"
},
"identifier1"
],
[
"command2",
{
"parameter1": "value",
"parameter2": "value"
},
"identifier2"
]
]
</nowiki>

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:

<nowiki>

son payload:

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

</nowiki>

submitting the command with curl:

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

command line equivalent

doveadm reload

=== successful response ===

<nowiki>

[
[
"doveadmResponse",
[],
"a2"
]
]
</nowiki>

=== failure response ===

<nowiki>

[
[
"error",
{
"exitCode": 68,
"type": "exitCode"
},
"a2"
]
</nowiki>

=== failure codes ===

{| class="wikitable"
|-
|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
|}

== Supported commands ==

== doveadm service ==
=== doveadm service stop ===

stop one or more dovecot services on target host

<nowiki>
{
"command": "serviceStop",
"parameters": [
{
"name": "service",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|service
|string array
|Name of service to stop
|[“imap”,”imap-hibernate”]
|}

example:

<nowiki>
[
[
"serviceStop",
{
"service": [
"imap",
"imap-hibernate"
]
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["serviceStop",{"service":["imap","imap-hibernate"]},"aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm service stop imap imap-hibernate
</nowiki>

=== doveadm stop ===

stop dovecot on the target host
<nowiki>

{
"command": "stop",
"parameters": []
}

no parameters
</nowiki>
example:
<nowiki>
[
[
"stop",
{},
"a1"
]
]

# curl -u doveadm:hellodoveadm -X POST http://localhost:8080/doveadm/v1 -H "Content-Type: application/json" -d '[["stop",{},"a1"]]'

CLI: doveadm stop
</nowiki>

=== doveadm reload ===

reload dovecot configuration

<nowiki>
{
"command": "reload",
"parameters": []
}
</nowiki>

example:

<nowiki>
[
[
"reload",
{},
"a2"
]
]

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

CLI: doveadm reload
</nowiki>

== doveadm stats ==
=== doveadm stats dump ===

dump collected dovecot statistics

<nowiki>
{
"command": "statsDump",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "type",
"type": "string"
},
{
"name": "filter",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|+parameters
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|type
|String
|Type of stats to dump
|global
|-
|filter
|String
|Dump filter
|last_update 1483101542
|}

Example:

<nowiki>
[
[
"statsDump",
{
"type": "global"
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["statsDump",{"type":"global"},"aa"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"auth_cache_hits": "0",
"auth_cache_misses": "0",
"auth_db_tempfails": "0",
"auth_failures": "0",
"auth_master_successes": "0",
"auth_successes": "0",
"clock_time": "0.0",
"disk_input": "0",
"disk_output": "0",
"fscache_read": "0",
"fscache_stat": "0",
"fscache_write": "0",
"idx_del": "0",
"idx_iter": "0",
"idx_read": "0",
"idx_read_usecs": "0",
"idx_wbytes": "0",
"idx_write": "0",
"idx_write_usecs": "0",
"invol_cs": "0",
"last_update": "0.000000",
"mail_cache_hits": "0",
"mail_lookup_attr": "0",
"mail_lookup_path": "0",
"mail_read_bytes": "0",
"mail_read_count": "0",
"maj_faults": "0",
"min_faults": "0",
"num_cmds": "0",
"num_connected_sessions": "0",
"num_logins": "0",
"obox_copy": "0",
"obox_del": "0",
"obox_iter": "0",
"obox_read": "0",
"obox_read_usecs": "0",
"obox_stat": "0",
"obox_wbytes": "0",
"obox_write": "0",
"obox_write_usecs": "0",
"read_bytes": "0",
"read_count": "0",
"reset_timestamp": "1483104199",
"sys_cpu": "0.0",
"user_cpu": "0.0",
"vol_cs": "0",
"write_bytes": "0",
"write_count": "0"
}
],
"aa"
]
]

CLI: doveadm stats dump global
</nowiki>

=== doveadm stats reset ===
reset dovecot statistics counters
<nowiki>

{
"command": "statsReset",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|}

example:

<nowiki>
[
[
"statsReset",
{},
"aa"
]
]

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

CLI: doveadm stats reset
</nowiki>

== doveadm penalty ==

<nowiki>
show current penalties

{
"command": "penalty",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "netmask",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|string
|Path to doveadm socket
|/var/run/dovecot-server
|-
|netmask
|string
|To reduce/filter the output supply an IP address or a network range in CIDR notation (ip/mask)
|10.0.0.0/24
|}

example:

<nowiki>
[
[
"penalty",
{},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["penalty",{},"aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm penalty
</nowiki>

== doveadm kick ==

Kick user from dovecot. Applicable to session in dovecot backend only

<nowiki>
{
"command": "kick",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "force",
"type": "boolean"
},
{
"name": "mask",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|force
|Boolean
|Do a forced kick?
|0
|-
|mask
|String
|Uid mask
|testuser001
|}

example:

<nowiki>
[
[
"kick",
{
"force": 0,
"mask": "testuser001"
},
"aa"
]
]

# curl -v -u doveadm:hellodoveadm –H “Content-Type: application/json" -d '[["kick", {"mask":"testuser001"}, "aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm kick testuser001
</nowiki>

response for succesfull kick:

<nowiki>
[
[
"doveadmResponse",
[
{
"result": "testuser001"
}
],
"aa"
]
]
</nowiki>

response in case kick failed:

<nowiki>
[
[
"error",
{
"exitCode": 68,
"type": "exitCode"
},
"aa"
]
]
</nowiki>

== doveadm who ==

<nowiki>
list active dovecot sessions

{
"command": "who",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "separateConnections",
"type": "boolean"
},
{
"name": "mask",
"type": "array"
}
]
}
</nowiki>

parameters

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|string
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|separateConnections
|Boolean
|Show each user connection in separate entries
|0
|-
|mask
|string array
|Uid mask
|testuser001
|}

Example:

<nowiki>
[
[
"who",
{
"mask": "",
"separateConnections": 0,
"socketPath": ""
},
"aa"
]
]

# curl -v -u doveadm:hellodoveadm -X POST http://localhost:ype: application/json" -d '[["who", {}, "aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm who
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"connections": "1",
"ips": "(127.0.0.1)",
"pids": "(4999)",
"service": "imap",
"username": "testuser001"
}
],
"aa"
]
]
</nowiki>

== doveadm director ==
=== doveadm director status ===

Show backend statuses on directors. Available only in directors

<nowiki>
[
{
"command": "directorStatus",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "tag",
"type": "string"
}
]
}
]
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|String
|Show director status for Tagged hosts only
|NewBackend
|}

example:

<nowiki>
[
[
"directorStatus",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorStatus",{},"bb"]]' http://localhost:8080/doveadm/v1

</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"mail server ip": "10.0.0.234",
"state": "up",
"state-changed": "2016-12-15 08:31:37",
"tag": "",
"users": "1",
"vhosts": "100"
},
{
"mail server ip": "10.0.0.235",
"state": "up",
"state-changed": "2016-12-15 08:31:04",
"tag": "",
"users": "0",
"vhosts": "100"
}
],
"bb"
]
]

CLI: doveadm director status
</nowiki>

=== doveadm director map ===

list current user → host mappings. Applicable to director only

<nowiki>

"command": "directorMap",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "usersFile",
"type": "string"
},
{
"name": "hashMap",
"type": "boolean"
},
{
"name": "userMap",
"type": "boolean"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

parameters

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|usersFile
|String
|provide Path to users list. One username per line
|/etc/dovecot/userlist.txt
|-
|hashMap
|Boolean
|Output users as hashmap
|True
|-
|userMap
|Boolean
|Output users as userlist
|True
|-
|host
|String
|Show only mappings to given host
|10.0.0.234
|}

example:

<nowiki>
[
[
"directorMap",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorMap",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"expire time": "2016-12-30 14:52:56",
"hash": "3853430566",
"mail server ip": "10.0.0.235",
"user": "samik"
}
],
"bb"
]
]

CLI: doveadm director map
</nowiki>

=== doveadm director add ===

add backend to director ring

<nowiki>
{
"command": "directorAdd",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "tag",
"type": "string"
},
{
"name": "host",
"type": "string"
},
{
"name": "vhostCount",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|tag
|String
|apply tag to backend
|/etc/dovecot/userlist.txt
|-
|host
|String
|backend ip to add
|10.0.0.234
|-
|vhostCount
|String
|vhost count to add
|100
|}

Example:

<nowiki>
[
[
"directorAdd",
{
"host": "10.0.234"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorAdd",{"host":"10.0.234"},"bb"]]' http://localhost:8080/doveadm/v1

CLI: doveadm director add 10.0.0.234
</nowiki>

=== doveadm director update ===

<nowiki>
{
"command": "directorUpdate",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
},
{
"name": "vhostCount",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|string
|Show director status for tagged hosts only
|NewBackend
|}

=== doveadm director up ===

<nowiki>
{
"command": "directorUp",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|string
|Show director status for tagged hosts only
|NewBackend
|}

=== doveadm director down ===

<nowiki>
{
"command": "directorDown",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|string
|Show director status for tagged hosts only
|NewBackend
|}

=== doveadm director remove ===

remove backend from director ring

<nowiki>
{
"command": "directorRemove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|host
|String
|backend to remove
|10.0.0.134
|}

example:

<nowiki>
[
[
"directorRemove",
{
"host": "10.0.0.234"
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRemove",{"host":"10.0.0.234"},"aa"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"aa"
]
]

CLI: doveadm director remove 10.0.0.234
</nowiki>

=== doveadm director move ===

move user mapping from backend to another or create director mapping for an user
<nowiki>
{
"command": "directorMove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|user
|String
|User uid to move
|testuser001
|-
|host
|string
|Target backend ip as listed in doveadm doveadm director status
|10.0.0.234
|}

example:

<nowiki>
[
[
"directorMove",
{
"host": "10.0.234",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorMove",{"user":"samik","host":"10.0.234"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director move samik 10.0.0.234
</nowiki>

== doveadm director kick ==

<nowiki>
{
"command": "directorKick",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|user
|String
|uid of user to kick
|samik
|}

example:

<nowiki>
[
[
"directorKick",
{
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorKick",{"user":"samik"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director kick samik
</nowiki>

=== doveadm director flush ===

flush connection mappings to one backend at director level. All users mapped to given host will be flushed from the hashmap table and will be redistributed to backends.

Parameters:

<nowiki>
{
"command": "directorFlush",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "forceFlush",
"type": "boolean"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|forceFlush
|Boolean
|Flag to make flush forced
|True
|-
|host
|String
|Backend ip address from doveadm director status list
|10.0.0.234
|}

example:

<nowiki>
[
[
"directorFlush",
{
"host": "10.0.0.234"
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorFlush",{"host":"10.0.0.234"},"aa"]]' http://localhost:8080/doveadm/v1

</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"aa"
]
]
CLI: doveadm director flush 10.0.234
</nowiki>

=== doveadm director dump ===

Dumb the current director backend host configuration as commands

<nowiki>
{
"command": "directorDump",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|}

example:

<nowiki>
[
[
"directorDump",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorDump",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"command": "add",
"host": "10.0.0.234",
"socket-path": "/var/run/dovecot/director-admin",
"vhost_count": "100"
},
{
"command": "add",
"host": "10.0.0.235",
"socket-path": "/var/run/dovecot/director-admin",
"vhost_count": "100"
}
],
"bb"
]
]

CLI: doveadm director dump
</nowiki>

=== doveadm director ring add ===

add new director to director ring

parameters:

<nowiki>
{
"command": "directorRingAdd",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "ip",
"type": "string"
},
{
"name": "port",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|ip
|String
|director ip address to add
|10.0.0.233
|-
|port
|String
|port number to use if not default
|9143
|}

example:

<nowiki>
[
[
"directorRingAdd",
{
"ip": "10.0.0.233"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRingAdd",{"ip":"10.0.0.233"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director ring add 10.0.0.233
</nowiki>

=== doveadm director ring remove ===

remove director from director ring

parameters:

<nowiki>
{
"command": "directorRingRemove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "ip",
"type": "string"
},
{
"name": "port",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|ip
|String
|director ip to remove
|10.0.0.233
|-
|port
|String
|director service port if not default
|9143
|}

example:

<nowiki>
[
[
"directorRingRemove",
{
"ip": "10.0.0.233"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRingRemove",{"ip":"10.0.0.233"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director ring remove 10.0.0.233
</nowiki>

=== doveadm director ring status ===

show director ring status

parameters:

<nowiki>

{
"command": "directorRingStatus",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|}

example:

<nowiki>
[
[
"directorRingStatus",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRingStatus",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>

[
"doveadmResponse",
[
{
"director ip": "10.0.0.232",
"last failed": "never",
"port": "9143",
"status": "synced",
"type": "self"
},
{
"director ip": "10.0.0.233",
"last failed": "never",
"port": "9143",
"status": "",
"type": ""
}
],
"bb"
]
]

CLI: doveadm director ring status
</nowiki>

== doveadm proxy ==

The doveadm proxy commands are used to list or kick active Dovecot proxy connections.

=== doveadm proxy list ===

list active connections in the dovecot proxy

parameters:

<nowiki>
{
"command": "proxyList",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|}

example:

<nowiki>
[
[
"proxyList",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["proxyList",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"dest-ip": "127.0.0.1",
"dest-port": "1143",
"service": "imap",
"src-ip": "10.0.0.153",
"username": "samik"
}
],
"bb"
]
]

CLI: doveadm proxy list
</nowiki>

=== doveadm proxy kick ===

kick user session from proxy. applicable to imap/pop3/managesieve sessions

parameters:

<nowiki>
{
"command": "proxyKick",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|userid to kick
|samik
|}

example:

<nowiki>
[
[
"proxyKick",
{
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["proxyKick",{"user":"samik"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"count": "1"
}
],
"bb"
]
]

CLI: doveadm proxy kick samik
</nowiki>

== doveadm logs errors ==

fetch errors log

paraments:

<nowiki>
{
"command": "logErrors",
"parameters": [
{
"name": "since",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|}

example:

<nowiki>
[
[
"logErrors",
{},
"a2"
]
]

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

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"prefix": "stats",
"text": "Stats client input error: Invalid level",
"timestamp": "Dec 09 16:24:00",
"type": "Error"
},
{
"prefix": "doveadm(127.0.0.1)",
"text": "read(/var/run/dovecot/stats) unexpectedly disconnected",
"timestamp": "Dec 09 16:24:00",
"type": "Fatal"
},
{
"prefix": "stats",
"text": "Stats client input error: Invalid level",
"timestamp": "Dec 09 16:24:22",
"type": "Error"
},
{
"prefix": "stats",
"text": "Stats client input error: Invalid level",
"timestamp": "Dec 09 16:27:48",
"type": "Error"
},
{
"prefix": "director",
"text": "Empty server list",
"timestamp": "Dec 09 16:29:13",
"type": "Error"
},
{
"prefix": "director",
"text": "Invalid value for director_mail_servers setting",
"timestamp": "Dec 09 16:29:13",
"type": "Fatal"
}
],
"a2"
]
]

CLI: doveadm log errors
</nowiki>

== doveadm dict ==
=== doveadm dict get ===

get user key value from configured dictionary

parameters:

<nowiki>
{
"command": "dictGet",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to query
|samik
|-
|dictUri
|String
|optional URI for dictionary to query
|
|-
|key
|String
|key to query
|
|}

=== doveadm dict set ===

set user key value in configured dictionary

parameters:

<nowiki>
{
"command": "dictSet",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
},
{
"name": "value",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|samik
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|key
|String
|dictionary key to modify
|
|-
|value
|string
|value to set
|
|}

=== doveadm dict unset ===

unset user key value in configured dictionary

parameters:

<nowiki>
{
"command": "dictUnset",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|key
|String
|dictionary key to unset
|
|}
== doveadm dict inc ==

increase users key value in dictionary

parameters:

<nowiki>
{
"command": "dictInc",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
},
{
"name": "difference",
"type": "integer"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|-
|key
|String
|dictionary key to increase
|
|-
|difference
|integer
|increment value
|
|}

=== doveadm dict iter ===

list user keys in dictionary

parameters:

<nowiki>
{
"command": "dictIter",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "exact",
"type": "boolean"
},
{
"name": "recurse",
"type": "boolean"
},
{
"name": "noValue",
"type": "boolean"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "prefix",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|exact
|Boolean
|list only exact matches
|
|-
|recurce
|Boolean
|do recursive search
|
|-
|noValue
|Boolean
|list also keys that have no value set
|
|-
|prefix
|String
|search only keys with given prefix
|
|}

== doveadm fs ==
=== doveadm fs get ===

get object from storage

parameters:

<nowiki>
{
"command": "fsGet",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem to fetch
|
|}

=== doveadm fs put ===

put object to storage

parameters:

<nowiki>
{
"command": "fsPut",
"parameters": [
{
"name": "hash",
"type": "string"
},
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "inputPath",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|hash
|string
|
|
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|inputPath
|String
|source object path in local filesystem
|
|-
|path
|String
|object path filesystem to put
|
|}

=== doveadm fs copy ===

copy object in storage

parameters:

<nowiki>
{
"command": "fsCopy",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "sourcePath",
"type": "string"
},
{
"name": "destinationPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|sourcePathh
|String
|source object path
|
|-
|Destination path
|String
|destination object path in filesystem
|
|}

=== doveadm fs stat ===

fetch fs driver statistics

parameters:

<nowiki>
{
"command": "fsStat",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem fetch statistics for
|
|}

=== doveadm fs metadata ===

get filesystem object metadata

parameters:

<nowiki>
{
"command": "fsMetadata",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem fetch statistics for
|
|}

=== doveadm fs delete ===

delete object from storage

<nowiki>
{
"command": "fsDelete",
"parameters": [
{
"name": "recursive",
"type": "boolean"
},
{
"name": "maxParallel",
"type": "integer"
},
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem fetch statistics for
|
|-
|recursive
|Boolean
|do a recursive delete of path
|
|-
|maxParallel
|integer
|max number of parallel workers
|
|}

=== doveadm fs iter ===

list objects in given fs path

parameters:

<nowiki>
{
"command": "fsIter",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|path in filesystem to list
|
|}

=== doveadm fs iter-dirs ===
ist subfolders in given path

parameters:

<nowiki>
{
"command": "fsIterDirs",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|path in filesystem to list for subfolders
|
|}

== doveadm auth cache flush ==

flush authentication cache for one user or all users

parameters:

<nowiki>
{
"command": "authCacheFlush",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String array
|optional list of users in flush
|[“samik”,”samitest”]
|}

example:

<nowiki>
[
[
"authCacheFlush",
{
"user": [
"samik"
]
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["authCacheFlush",{"user":["samik"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"entries": "0"
}
],
"bb"
]
]

CLI: doveadm auth cache flush samik
</nowiki>

== doveadm user ==

do a userdb lookup for an user

<nowiki>
{
"command": "user",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "authInfo",
"type": "array"
},
{
"name": "field",
"type": "string"
},
{
"name": "expandField",
"type": "string"
},
{
"name": "userdbOnly",
"type": "boolean"
},
{
"name": "userMask",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|authInfo
|String array
|auth_info specifies additional conditions for the user command. The auth_info option string has to be given as name=value pair. For multiple conditions the -x option could be supplied multiple times.
Possible names for the auth_info are:
service
The service for which the userdb lookup should be tested. The value may be the name of a service, commonly used with Dovecot. For example: imap, pop3 or smtp.
lip
The local IP address (server) for the test.
rip
The remote IP address (client) for the test.
lport
The local port, e.g. 143
rport
The remote port, e.g. 24567
|sevice=imap
|-
|field
|String
|fetch only one specified field instead of all
|
|-
|expandField
|String
|expand configuration variable with user specific values
|
|-
|userdbOnly
|Boolean
|only fetch from userdb lookup and don’t process passdb
|
|-
|userMask
|String array
|search filter
|
|}

example:

<nowiki>
[
[
"user",
{
"userMask": [
"samik"
]
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["user",{"userMask":["samik"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
{
"samik": {
"gid": "1000",
"home": "/var/vmail/samik",
"junkflag": "0",
"mail": "Maildir:/mails/mails/samik/Maildir",
"namespace/Junk/hidden": "no",
"namespace/Junk/list": "yes",
"uid": "1000"
}
},
"bb"
]
]

CLI: doveadm user samik
</nowiki>

== doveadm mailbox ==
=== doveadm mailbox metadata set ===

set user mailbox metadata

parameters:

<nowiki>
{
"command": "mailboxMetadataSet",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "key",
"type": "string"
},
{
"name": "value",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata set
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to set
|
|-
|value
|String
|metadata value to set
|
|}

example:

<nowiki>
[
[
"mailboxMetadataSet",
{
"key": "/private/comment",
"mailbox": "INBOX",
"user": "samik",
"value": "test"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataSet",{"user":"samik","mailbox":"INBOX","key":"/private/comment","value":"test"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox metadata set –u samik INBOX /private/comment test
</nowiki>

=== doveadm mailbox metadata unset ===

unset user mailbox metadata

parameters:

<nowiki>
{
"command": "mailboxMetadataUnset",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata unset
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to unset
|
|}

example:

<nowiki>
[
[
"mailboxMetadataUnset",
{
"key": "/private/comment",
"mailbox": "INBOX",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataUnset",{"user":"samik","mailbox":"INBOX","key":"/private/comment"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox metadata unset –u samik INBOX /private/comment
</nowiki>

=== doveadm mailbox metadata get ===

get user mailbox metadata

parameters:

<nowiki>
{
"command": "mailboxMetadataGet",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata get
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to get
|
|}

example:

<nowiki>
[
[
"mailboxMetadataGet",
{
"key": "/private/comment",
"mailbox": "INBOX",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataGet",{"user":"samik","mailbox":"INBOX","key":"/private/comment"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response

<nowiki>
[
[
"doveadmResponse",
[
{
"value": "plaa"
}
],
"bb"
]
]

CLI: doveadm mailbox metadata get –u samik INBOX /private/comment
</nowiki>

=== doveadm mailbox list ===

list user mailbox metadata for a folder

parameters:

<nowiki>

"command": "mailboxMetadataList",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "keyPrefix",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata get
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to get
|
|-
|keyPrefix
|String
|search prefix for keys
|
|-
|mailbox
|String
|mailbox to fetch metadata from
|
|}

example:

<nowiki>
[
[
"mailboxMetadataList",
{
"mailbox": "INBOX",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataList",{"user":"samik","mailbox":"INBOX"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"key": "comment"
},
{
"key": "specialuse"
}
],
"bb"
]
]

CLI: doveadm mailbox metadata list –u samik INBOX
</nowiki>

=== doveadm mailbox status ===

fetch user mailbox status

parameters:

<nowiki>
{
"command": "mailboxStatus",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "totalSum",
"type": "boolean"
},
{
"name": "field",
"type": "array"
},
{
"name": "mailboxMask",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply status fetch
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|totalSum
|boolean
|
|
|-
|field
|String array
|fields to fetch
|all
|-
|mailboxMask
|String array
|fetch status on given mailboxes
|
|}

example:

<nowiki>

[
[
"mailboxStatus",
{
"field": [
"all"
],
"mailboxMask": [
"INBOX",
"INBOX/*",
"*"
],
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxStatus",{"user":"samik","field":["all"],"mailboxMask":["INBOX","INBOX/*","*"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"guid": "21b588150b156558eb3500007afd792c",
"highestmodseq": "5",
"mailbox": "Junk",
"messages": "0",
"recent": "0",
"uidnext": "1",
"uidvalidity": "1483019529",
"unseen": "0",
"vsize": "0"
},
{
"guid": "21b588150b156558eb3500007afd792c",
"highestmodseq": "5",
"mailbox": "INBOX",
"messages": "0",
"recent": "0",
"uidnext": "1",
"uidvalidity": "1483019529",
"unseen": "0",
"vsize": "0"
}
],
"bb"
]
]

CLI: doveadm mailbox status –u samik all “*”
</nowiki>

=== doveadm mailbox list ===

fetch user folder list

parameters:

<nowiki>
{
"command": "mailboxList",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mutf7",
"type": "boolean"
},
{
"name": "utf8",
"type": "boolean"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "mailboxMask",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid to apply mailbox list
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|mutf7
|Boolean
|
|
|-
|utf8
|Boolean
|fetch only certain fields instead of all
|
|-
|subscription
|Boolean
|
|
|-
|mailboxMask
|String array
|fetch list of given mailboxes
|
|}

example:

<nowiki>
[
[
"mailboxList",
{
"user": "samik"
},
"bb"
]
]
# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxList",{"user":"samik"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"mailbox": "Junk"
},
{
"mailbox": "INBOX"
}
],
"bb"
]
]

CLI: doveadm mailbox list –u samik
</nowiki>

=== doveadm mailbox create ===
create mailbox folder for user

parameters:

<nowiki>
{
"command": "mailboxCreate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "guid",
"type": "string"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply mailbox create
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|subscription
|Boolean
|
|
|-
|mailbox
|String array
|list of mailbox folders to create
|
|}

example:

<nowiki>
[
[
"mailboxCreate",
{
"mailbox": [
"INBOX/myfolder"
],
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxCreate",{"user":"samik","mailbox":["INBOX/myfolder"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>

[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox create –u samik INBOX/myfolder
</nowiki>

=== doveadm mailbox delete ===

delete user mailbox folder

parameters:

<nowiki>
{
"command": "mailboxDelete",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "requireEmpty",
"type": "boolean"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "recursive",
"type": "boolean"
},
{
"name": "unsafe",
"type": "boolean"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply delete
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|requireEmpty
|Boolean
|only delete if folder is empty
|
|-
|subscription
|Boolean
|
|
|-
|recursive
|Boolean
|delete also subfolders
|
|-
|unsafe
|Boolean
|
|
|-
|mailbox
|String array
|list of mailbox folders to create
|
|}

example:

<nowiki>
[
[
"mailboxDelete",
{
"mailbox": [
"INBOX/myfolder"
],
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxDelete",{"user":"samik","mailbox":["INBOX/myfolder"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox delete –u samik INBOX/myfolder
</nowiki>

=== doveadm mailbox rename ===

rename user folder

parameters:

<nowiki>
{
"command": "mailboxRename",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "newName",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply mailbox rename
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|subscriptions
|Boolean
|
|
|-
|newName
|String
|mailbox new name
|
|-
|mailbox
|String
|mailbox to rename
|
|}

example:

<nowiki>
[
[
"mailboxRename",
{
"mailbox": "INBOX/myfolder",
"newName": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxRename",{"user":"samik","mailbox":"INBOX/myfolder","newName":"INBOX/myfoldertoo"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox rename –u samik INBOX/myfolder INBOX/myfoldertoo
</nowiki>

=== doveadm mailbox subscribe ===

subscribe user to a mailbox

parameters:

<nowiki>
{
"command": "mailboxSubscribe",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply subscribe
|
|-
|userFile
|String
|optionally fetch usernames from. One username per line
|
|-
|mailbox
|String
|mailbox to subscribe
|
|}

example:

<nowiki>
[
[
"mailboxSubscribe",
{
"mailbox": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxSubscribe",{"user":"samik","mailbox":"INBOX/myfoldertoo"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:
<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox subscribe –u samik INBOX/myfoldertoo
</nowiki>

=== doveadm mailbox unsubscribe ===

unsubscribe user from an folder

parameters:

<nowiki>
{
"command": "mailboxUnsubscribe",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply unsubscribe
|
|-
|userFile
|String
|optionally fetch usernames from. One username per line
|
|-
|mailbox
|String
|mailbox to unsubscribe
|
|}

example:

<nowiki>
[
[
"mailboxUnsubscribe",
{
"mailbox": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxUnsubscribe",{"user":"samik","mailbox":"INBOX/myfoldertoo"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox unsubscribe –u samik INBOX/myfoldertoo
</nowiki>

=== doveadm mailbox update ===

update user mailbox information

parameters:

<nowiki>
{
"command": "mailboxUpdate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailboxGuid",
"type": "string"
},
{
"name": "uidValidity",
"type": "string"
},
{
"name": "minNextUid",
"type": "string"
},
{
"name": "minFirstRecentUid",
"type": "string"
},
{
"name": "minHighestModseq",
"type": "string"
},
{
"name": "minHighestPvtModseq",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply update
|
|-
|userFile
|String
|optionally fetch usernames from. One username per line
|
|-
|mailbox
|String
|mailbox to unsubscribe
|
|-
|mailboxGuid
|String
|set mailbox guid
|
|-
|uidValidity
|String
|set mailbox uidvalidity
|
|-
|minNextuid
|String
|set mailbox minimum next uid
|
|-
|minFirstRecentuid
|String
|set mailbox minimum recent uid
|
|-
|minHighestModseq
|String
|
|
|-
|minHighestPvtModseq
|String
|
|
|}

=== doveadm mailbox save ===

save mail into users mailbox

parameters:

<nowiki>
{
"command": "save",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "file",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to save mail into
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|mailbox
|String
|mailbox to unsubscribe
|
|-
|file
|String
|mail to inject
|
|}

example:

<nowiki>
[
[
"save",
{
"file": "From: Joulu Pukki <joulu.pukki@korvatunturi.fi>\nSubject: plaa\n\nmail body\n",
"mailbox": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["save",{"user":"samik","mailbox":"INBOX/myfoldertoo","file":"From: Joulu Pukki <joulu.pukki@korvatunturi.fi>\nSubject: plaa\n\nmail body\n"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]
</nowiki>

== doveadm fetch ==

fetch data from user mailbox

parameters:

<nowiki>
{
"command": "fetch",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "field",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to fetch data
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|field
|String array
|fields to fetch. Supported fields as of dovecot 2.2.26: hdr.<name> body.<section> binary.<section> user mailbox mailbox-guid seq uid guid flags modseq hdr body body.snippet text text.utf8 size.physical size.virtual date.received date.sent date.saved date.received.unixtime date.sent.unixtime date.saved.unixtime imap.envelope imap.body imap.bodystructure pop3.uidl pop3.order refcount storageid
|
|-
|query
|String array
|search query to user
|
|}

example:

<nowiki>
[
[
"fetch",
{
"field": [
"text"
],
"query": [
"mailbox",
"INBOX/myfoldertoo"
],
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["fetch",{"user":"samik","field":["text"],"query":["mailbox","INBOX/myfoldertoo"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"text": "From: Joulu Pukki <joulu.pukki@korvatunturi.fi>\nSubject: plaa\n\nmail body\n"
}
],
"bb"
]
]

CLI: doveadm fetch –u samik “text” mailbox INBOX/myfoldertoo
</nowiki>

== doveadm index ==

index user mailbox folder or folders

parameters:

<nowiki>
{
"command": "index",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "queue",
"type": "boolean"
},
{
"name": "maxRecent",
"type": "string"
},
{
"name": "mailboxMask",
"type": "string"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to index
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|query
|Boolean
|max number of recent mails to index
|
|-
|maxRecent
|String
|max number of recent mails to index
|
|-
|mailboxMask
|String
|mailbox search mask to apply indexing into
|
|}

example:

<nowiki>
[
[
"index",
{
"mailboxMask": "INBOX*",
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["index",{"user":"samik","mailboxMask":"INBOX*"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm index –u samik “INBOX*”
</nowiki>

== doveadm altmove ==

move mails between primary and alternative mailbox storage locations. Applicable to mdbox and sdbox mailbox formats only

parameters:

<nowiki>
{
"command": "altmove",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "reverse",
"type": "boolean"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to apply move
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|reverse
|Boolean
|search query to apply to mail move
|
|-
|query
|String array
|search query to apply to mail move
|
|}

example:

<nowiki>
[
[
"altmove",
{
"query": [
"mailbox",
"INBOX/myfoldertoo",
"savedbefore",
"since",
"30d"
],
"reverse": 0,
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["altmove",{"user":"samik","reverse":0,"query":["mailbox","INBOX/myfoldertoo","savedbefore","since","30d"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

== doveadm deduplicate ==

This command is used to expunge duplicated messages in mailboxes

parameters:

<nowiki>
{
"command": "deduplicate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "byMsgid",
"type": "boolean"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to deduplicate
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|byMsgId
|Boolean
|deduplicate by Message-ID instead of guid
|
|-
|query
|String array
|search query to apply to deduplicate
|
|}

== doveadm expunge ==

Expunge messages matching given search query

parameters:

<nowiki>
{
"command": "expunge",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "deleteEmptyMailbox",
"type": "boolean"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to expunge
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|deleteEmptyMailbox
|Boolean
|delete also mailbox if it’s empty after expunge has been applied
|
|-
|query
|String array
|search query to apply to expunge
|
|}

== doveadm flags ==
add, remove or replace messages' flags

=== doveadm flags add ===

add flag to a message or messages

parameters:

<nowiki>
{
"command": "flagsAdd",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "flag",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to add flags
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|flag
|String array
|list of flags to add
|
|-
|query
|String array
|search query to apply to flag add
|
|}

=== doveadm flags remove ===

remove flags from message or messages

parameters:

<nowiki>
{
"command": "flagsRemove",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "flag",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to add flags
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|flag
|String array
|list of flags to remove
|
|-
|query
|String array
|search query to apply to flag remove
|
|}

=== doveadm flags replace ===

Replace flags with another flag in message or messages. Replaces all current flags with the ones in the parameter list

parameters:

<nowiki>
{
"command": "flagsReplace",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "flag",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to replace flags
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|flag
|String array
|list of flags to replace with
|
|-
|query
|String array
|search query to apply to flag replace
|
|}

== doveadm import ==

Import messages matching given search query

parameters:

<nowiki>
{
"command": "import",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "subscribe",
"type": "boolean"
},
{
"name": "sourceLocation",
"type": "string"
},
{
"name": "destParentMailbox",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to apply import
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|subscribe
|boolean
|when enabled possible newly created folders are also subscibed
|
|-
|sourceLocation
|String
|location of source mailboxes
|
|-
|destParentMailbox
|String
|destination parent mailbox where to import
|
|-
|query
|String array
|search query for messages to import
|
|}

== doveadm force-resync ==

Under certain circumstances it may happen, that dovecot is unable to automatically solve problems with mailboxes. In such situations the force-resync command may be helpful. It tries to fix all problems. For sdbox and mdbox mailboxes the storage files will be also checked.

parameters:

<nowiki>
{
"command": "forceResync",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailboxMask",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|user
|String
|uid of user to apply resync
|
|-
|mailboxMask
|String
|apply forced resync on given mailboxes
|INBOX*
|}

example:

<nowiki>
[
[
"forceResync",
{
"mailboxMask": "INBOX*",
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["forceResync",{"user":"samik","mailboxMask":"INBOX*"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm force-resync –u samik “INBOX*”
</nowiki>

== doveadm purge ==

Remove messages with refcount=0 from mdbox files

parameters:

<nowiki>
{
"command": "purge",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to apply purge
|
|}

== doveadm search ==

Show a list of mailbox GUIDs and message UIDs matching given search query

parameters:

<nowiki>
{
"command": "search",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|user
|String
|uid of user to apply purge
|
|-
|query
|String array
|search query
|
|}

example:

<nowiki>
[
[
"search",
{
"query": [
"mailbox",
"INBOX*",
"all"
],
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["search",{"user":"samik","query":["mailbox","INBOX*","all"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"mailbox-guid": "cf497f128caf7c58612200007afd792c",
"uid": "1"
}
],
"bb"
]
]

CLI: doveadm search –u samik mailbox “INBOX*” all
</nowiki>

== doveadm copy ==

Copy messages matching the given search query into another mailbox

parameters:

<nowiki>
{
"command": "copy",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "destinationMailbox",
"type": "string"
},
{
"name": "sourceType",
"type": "string"
},
{
"name": "sourceUser",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm move ==

Move messages matching the given search query into another mailbox

parameters:

<nowiki>
{
"command": "move",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "destinationMailbox",
"type": "string"
},
{
"name": "sourceType",
"type": "string"
},
{
"name": "sourceUser",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm fscache rescan ==

force fscache rescan

parameters:

<nowiki>
{
"command": "fscacheRescan",
"parameters": [
{
"name": "path",
"type": "string"
},
{
"name": "maxAge",
"type": "integer"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm metacache ==
=== doveadm metacache clean ===

clean metacache content for given user or all users

parameters:

<nowiki>
{

"command": "metacacheClean",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "days",
"type": "integer"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache flush ===

flush metacache contents to storage for given user or all users

parameters:

<nowiki>
{
"command": "metacacheFlush",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache unpack ===

unpack metacache index bundle to target directory

parameters:

<nowiki>
{
"command": "metacacheUnpack",
"parameters": [
{
"name": "bundleName",
"type": "string"
},
{
"name": "bundle",
"type": "string"
},
{
"name": "destinationDirectory",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache flushall ===

flush metacache to storage for all users

parameters:

<nowiki>
{
"command": "metacacheFlushall",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache remove ===

remove metacache for given mask

parameters:

<nowiki>
{
"command": "metacacheRemove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "mask",
"type": "string"
}
]
}
</nowiki>
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache list ===

list local metacache contents

parameters:

<nowiki>
{
"command": "metacacheList",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm obox user delete ==

delete user data from storage, Cassandra and local caches (metacache and fscache).

parameters:

<nowiki>
{
"command": "oboxUserDelete",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

example:

<nowiki>
[
[
"oboxUserDelete",
{
"allUsers": 0,
"socketPath": "",
"user": "testuser003",
"userFile": ""
},
"aa"
]
]

# curl -v -u doveadm:hellodoveadm -X POST http://localhost:ype: application/json" -d '[["oboxUserDelete", {"allUsers":0,"user":"testuser003"}, "aa"]]'
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"aa"
]
]

CLI: doveadm obox user delete –u testuser003
</nowiki>

== doveadm sieve ==

Commands related to handling Sieve scripts.

=== doveadm sieve list ===

list user sieve scripts

parameters:

<nowiki>
{
"command": "sieveList",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve get ===

get user sieve script

parameters:

<nowiki>
{
"command": "sieveGet",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "scriptname",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve put ===

inject sieve script to user

parameters:

<nowiki>
{
"command": "sievePut",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "activate",
"type": "boolean"
},
{
"name": "scriptname",
"type": "string"
},
{
"name": "file",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve delete ===

delete user sieve

parameters:

<nowiki>
{
"command": "sieveDelete",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "ignoreActive",
"type": "boolean"
},
{
"name": "scriptname",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve activate ===

activate user sieve script

parameters:

<nowiki>
{
"command": "sieveActivate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "scriptname",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve deactivate ===

deactivate user sieve

parameters:

<nowiki>
{
"command": "sieveDeactivate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve rename ===

rename user sieve script

parameters:

<nowiki>
{
"command": "sieveRename",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "oldname",
"type": "string"
},
{
"name": "newname",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm fts ==
Dovecot fts indexing commands.

=== doveadm fts lookup ===

query user fts indexed data

parameters:

<nowiki>
{
"command": "ftsLookup",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts expand ===

<nowiki>
{
"command": "ftsExpand",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts tokenize ===

<nowiki>
{
"command": "ftsTokenize",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "language",
"type": "string"
},
{
"name": "text",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts optimize ===

<nowiki>
{
"command": "ftsOptimize",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts rescan ===

<nowiki>
{
"command": "ftsRescan",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

Template:DoveadmHTTPapi

2017-03-15T12:11:26Z

Oskarikentta: /* doveadm dict inc */

== Table of Contents ==
__TOC__

== 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:

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

=== 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:

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

Basic auth usage:
<nowiki>
curl -H "Authorization: Basic <base64 doveadm:doveadm_password>"
http://host:port/doveadm/v1
</nowiki>
or by letting curl to form the base64 encoded authentication basig authentication header:

<nowiki>
curl –u doveadm:password http://host:port/doveadm/v1
</nowiki>

=== 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:

<nowiki>

[
[
"command1",
{
"parameter1": "value",
"parameter2": "value",
"parameter3": "value"
},
"identifier"
]
]
</nowiki>
Multiple commands can be submitted in one json payload:
<nowiki>
[
[
"command1",
{
"parameter1": "value",
"parameter2": "value"
},
"identifier1"
],
[
"command2",
{
"parameter1": "value",
"parameter2": "value"
},
"identifier2"
]
]
</nowiki>

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:

<nowiki>

son payload:

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

</nowiki>

submitting the command with curl:

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

command line equivalent

doveadm reload

=== successful response ===

<nowiki>

[
[
"doveadmResponse",
[],
"a2"
]
]
</nowiki>

=== failure response ===

<nowiki>

[
[
"error",
{
"exitCode": 68,
"type": "exitCode"
},
"a2"
]
</nowiki>

=== failure codes ===

{| class="wikitable"
|-
|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
|}

== Supported commands ==

== doveadm service ==
=== doveadm service stop ===

stop one or more dovecot services on target host

<nowiki>
{
"command": "serviceStop",
"parameters": [
{
"name": "service",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|service
|string array
|Name of service to stop
|[“imap”,”imap-hibernate”]
|}

example:

<nowiki>
[
[
"serviceStop",
{
"service": [
"imap",
"imap-hibernate"
]
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["serviceStop",{"service":["imap","imap-hibernate"]},"aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm service stop imap imap-hibernate
</nowiki>

=== doveadm stop ===

stop dovecot on the target host
<nowiki>

{
"command": "stop",
"parameters": []
}

no parameters
</nowiki>
example:
<nowiki>
[
[
"stop",
{},
"a1"
]
]

# curl -u doveadm:hellodoveadm -X POST http://localhost:8080/doveadm/v1 -H "Content-Type: application/json" -d '[["stop",{},"a1"]]'

CLI: doveadm stop
</nowiki>

=== doveadm reload ===

reload dovecot configuration

<nowiki>
{
"command": "reload",
"parameters": []
}
</nowiki>

example:

<nowiki>
[
[
"reload",
{},
"a2"
]
]

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

CLI: doveadm reload
</nowiki>

== doveadm stats ==
=== doveadm stats dump ===

dump collected dovecot statistics

<nowiki>
{
"command": "statsDump",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "type",
"type": "string"
},
{
"name": "filter",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|+parameters
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|type
|String
|Type of stats to dump
|global
|-
|filter
|String
|Dump filter
|last_update 1483101542
|}

Example:

<nowiki>
[
[
"statsDump",
{
"type": "global"
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["statsDump",{"type":"global"},"aa"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"auth_cache_hits": "0",
"auth_cache_misses": "0",
"auth_db_tempfails": "0",
"auth_failures": "0",
"auth_master_successes": "0",
"auth_successes": "0",
"clock_time": "0.0",
"disk_input": "0",
"disk_output": "0",
"fscache_read": "0",
"fscache_stat": "0",
"fscache_write": "0",
"idx_del": "0",
"idx_iter": "0",
"idx_read": "0",
"idx_read_usecs": "0",
"idx_wbytes": "0",
"idx_write": "0",
"idx_write_usecs": "0",
"invol_cs": "0",
"last_update": "0.000000",
"mail_cache_hits": "0",
"mail_lookup_attr": "0",
"mail_lookup_path": "0",
"mail_read_bytes": "0",
"mail_read_count": "0",
"maj_faults": "0",
"min_faults": "0",
"num_cmds": "0",
"num_connected_sessions": "0",
"num_logins": "0",
"obox_copy": "0",
"obox_del": "0",
"obox_iter": "0",
"obox_read": "0",
"obox_read_usecs": "0",
"obox_stat": "0",
"obox_wbytes": "0",
"obox_write": "0",
"obox_write_usecs": "0",
"read_bytes": "0",
"read_count": "0",
"reset_timestamp": "1483104199",
"sys_cpu": "0.0",
"user_cpu": "0.0",
"vol_cs": "0",
"write_bytes": "0",
"write_count": "0"
}
],
"aa"
]
]

CLI: doveadm stats dump global
</nowiki>

=== doveadm stats reset ===
reset dovecot statistics counters
<nowiki>

{
"command": "statsReset",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|}

example:

<nowiki>
[
[
"statsReset",
{},
"aa"
]
]

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

CLI: doveadm stats reset
</nowiki>

== doveadm penalty ==

<nowiki>
show current penalties

{
"command": "penalty",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "netmask",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|string
|Path to doveadm socket
|/var/run/dovecot-server
|-
|netmask
|string
|To reduce/filter the output supply an IP address or a network range in CIDR notation (ip/mask)
|10.0.0.0/24
|}

example:

<nowiki>
[
[
"penalty",
{},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["penalty",{},"aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm penalty
</nowiki>

== doveadm kick ==

Kick user from dovecot. Applicable to session in dovecot backend only

<nowiki>
{
"command": "kick",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "force",
"type": "boolean"
},
{
"name": "mask",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|force
|Boolean
|Do a forced kick?
|0
|-
|mask
|String
|Uid mask
|testuser001
|}

example:

<nowiki>
[
[
"kick",
{
"force": 0,
"mask": "testuser001"
},
"aa"
]
]

# curl -v -u doveadm:hellodoveadm –H “Content-Type: application/json" -d '[["kick", {"mask":"testuser001"}, "aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm kick testuser001
</nowiki>

response for succesfull kick:

<nowiki>
[
[
"doveadmResponse",
[
{
"result": "testuser001"
}
],
"aa"
]
]
</nowiki>

response in case kick failed:

<nowiki>
[
[
"error",
{
"exitCode": 68,
"type": "exitCode"
},
"aa"
]
]
</nowiki>

== doveadm who ==

<nowiki>
list active dovecot sessions

{
"command": "who",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "separateConnections",
"type": "boolean"
},
{
"name": "mask",
"type": "array"
}
]
}
</nowiki>

parameters

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|string
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|separateConnections
|Boolean
|Show each user connection in separate entries
|0
|-
|mask
|string array
|Uid mask
|testuser001
|}

Example:

<nowiki>
[
[
"who",
{
"mask": "",
"separateConnections": 0,
"socketPath": ""
},
"aa"
]
]

# curl -v -u doveadm:hellodoveadm -X POST http://localhost:ype: application/json" -d '[["who", {}, "aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm who
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"connections": "1",
"ips": "(127.0.0.1)",
"pids": "(4999)",
"service": "imap",
"username": "testuser001"
}
],
"aa"
]
]
</nowiki>

== doveadm director ==
=== doveadm director status ===

Show backend statuses on directors. Available only in directors

<nowiki>
[
{
"command": "directorStatus",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "tag",
"type": "string"
}
]
}
]
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|String
|Show director status for Tagged hosts only
|NewBackend
|}

example:

<nowiki>
[
[
"directorStatus",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorStatus",{},"bb"]]' http://localhost:8080/doveadm/v1

</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"mail server ip": "10.0.0.234",
"state": "up",
"state-changed": "2016-12-15 08:31:37",
"tag": "",
"users": "1",
"vhosts": "100"
},
{
"mail server ip": "10.0.0.235",
"state": "up",
"state-changed": "2016-12-15 08:31:04",
"tag": "",
"users": "0",
"vhosts": "100"
}
],
"bb"
]
]

CLI: doveadm director status
</nowiki>

=== doveadm director map ===

list current user → host mappings. Applicable to director only

<nowiki>

"command": "directorMap",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "usersFile",
"type": "string"
},
{
"name": "hashMap",
"type": "boolean"
},
{
"name": "userMap",
"type": "boolean"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

parameters

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|usersFile
|String
|provide Path to users list. One username per line
|/etc/dovecot/userlist.txt
|-
|hashMap
|Boolean
|Output users as hashmap
|True
|-
|userMap
|Boolean
|Output users as userlist
|True
|-
|host
|String
|Show only mappings to given host
|10.0.0.234
|}

example:

<nowiki>
[
[
"directorMap",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorMap",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"expire time": "2016-12-30 14:52:56",
"hash": "3853430566",
"mail server ip": "10.0.0.235",
"user": "samik"
}
],
"bb"
]
]

CLI: doveadm director map
</nowiki>

=== doveadm director add ===

add backend to director ring

<nowiki>
{
"command": "directorAdd",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "tag",
"type": "string"
},
{
"name": "host",
"type": "string"
},
{
"name": "vhostCount",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|tag
|String
|apply tag to backend
|/etc/dovecot/userlist.txt
|-
|host
|String
|backend ip to add
|10.0.0.234
|-
|vhostCount
|String
|vhost count to add
|100
|}

Example:

<nowiki>
[
[
"directorAdd",
{
"host": "10.0.234"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorAdd",{"host":"10.0.234"},"bb"]]' http://localhost:8080/doveadm/v1

CLI: doveadm director add 10.0.0.234
</nowiki>

=== doveadm director update ===

<nowiki>
{
"command": "directorUpdate",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
},
{
"name": "vhostCount",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|string
|Show director status for tagged hosts only
|NewBackend
|}

=== doveadm director up ===

<nowiki>
{
"command": "directorUp",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|string
|Show director status for tagged hosts only
|NewBackend
|}

=== doveadm director down ===

<nowiki>
{
"command": "directorDown",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|string
|Show director status for tagged hosts only
|NewBackend
|}

=== doveadm director remove ===

remove backend from director ring

<nowiki>
{
"command": "directorRemove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|host
|String
|backend to remove
|10.0.0.134
|}

example:

<nowiki>
[
[
"directorRemove",
{
"host": "10.0.0.234"
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRemove",{"host":"10.0.0.234"},"aa"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"aa"
]
]

CLI: doveadm director remove 10.0.0.234
</nowiki>

=== doveadm director move ===

move user mapping from backend to another or create director mapping for an user
<nowiki>
{
"command": "directorMove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|user
|String
|User uid to move
|testuser001
|-
|host
|string
|Target backend ip as listed in doveadm doveadm director status
|10.0.0.234
|}

example:

<nowiki>
[
[
"directorMove",
{
"host": "10.0.234",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorMove",{"user":"samik","host":"10.0.234"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director move samik 10.0.0.234
</nowiki>

== doveadm director kick ==

<nowiki>
{
"command": "directorKick",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|user
|String
|uid of user to kick
|samik
|}

example:

<nowiki>
[
[
"directorKick",
{
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorKick",{"user":"samik"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director kick samik
</nowiki>

=== doveadm director flush ===

flush connection mappings to one backend at director level. All users mapped to given host will be flushed from the hashmap table and will be redistributed to backends.

Parameters:

<nowiki>
{
"command": "directorFlush",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "forceFlush",
"type": "boolean"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|forceFlush
|Boolean
|Flag to make flush forced
|True
|-
|host
|String
|Backend ip address from doveadm director status list
|10.0.0.234
|}

example:

<nowiki>
[
[
"directorFlush",
{
"host": "10.0.0.234"
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorFlush",{"host":"10.0.0.234"},"aa"]]' http://localhost:8080/doveadm/v1

</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"aa"
]
]
CLI: doveadm director flush 10.0.234
</nowiki>

=== doveadm director dump ===

Dumb the current director backend host configuration as commands

<nowiki>
{
"command": "directorDump",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|}

example:

<nowiki>
[
[
"directorDump",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorDump",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"command": "add",
"host": "10.0.0.234",
"socket-path": "/var/run/dovecot/director-admin",
"vhost_count": "100"
},
{
"command": "add",
"host": "10.0.0.235",
"socket-path": "/var/run/dovecot/director-admin",
"vhost_count": "100"
}
],
"bb"
]
]

CLI: doveadm director dump
</nowiki>

=== doveadm director ring add ===

add new director to director ring

parameters:

<nowiki>
{
"command": "directorRingAdd",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "ip",
"type": "string"
},
{
"name": "port",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|ip
|String
|director ip address to add
|10.0.0.233
|-
|port
|String
|port number to use if not default
|9143
|}

example:

<nowiki>
[
[
"directorRingAdd",
{
"ip": "10.0.0.233"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRingAdd",{"ip":"10.0.0.233"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director ring add 10.0.0.233
</nowiki>

=== doveadm director ring remove ===

remove director from director ring

parameters:

<nowiki>
{
"command": "directorRingRemove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "ip",
"type": "string"
},
{
"name": "port",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|ip
|String
|director ip to remove
|10.0.0.233
|-
|port
|String
|director service port if not default
|9143
|}

example:

<nowiki>
[
[
"directorRingRemove",
{
"ip": "10.0.0.233"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRingRemove",{"ip":"10.0.0.233"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director ring remove 10.0.0.233
</nowiki>

=== doveadm director ring status ===

show director ring status

parameters:

<nowiki>

{
"command": "directorRingStatus",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|}

example:

<nowiki>
[
[
"directorRingStatus",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRingStatus",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>

[
"doveadmResponse",
[
{
"director ip": "10.0.0.232",
"last failed": "never",
"port": "9143",
"status": "synced",
"type": "self"
},
{
"director ip": "10.0.0.233",
"last failed": "never",
"port": "9143",
"status": "",
"type": ""
}
],
"bb"
]
]

CLI: doveadm director ring status
</nowiki>

== doveadm proxy ==

The doveadm proxy commands are used to list or kick active Dovecot proxy connections.

=== doveadm proxy list ===

list active connections in the dovecot proxy

parameters:

<nowiki>
{
"command": "proxyList",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|}

example:

<nowiki>
[
[
"proxyList",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["proxyList",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"dest-ip": "127.0.0.1",
"dest-port": "1143",
"service": "imap",
"src-ip": "10.0.0.153",
"username": "samik"
}
],
"bb"
]
]

CLI: doveadm proxy list
</nowiki>

=== doveadm proxy kick ===

kick user session from proxy. applicable to imap/pop3/managesieve sessions

parameters:

<nowiki>
{
"command": "proxyKick",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|userid to kick
|samik
|}

example:

<nowiki>
[
[
"proxyKick",
{
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["proxyKick",{"user":"samik"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"count": "1"
}
],
"bb"
]
]

CLI: doveadm proxy kick samik
</nowiki>

== doveadm logs errors ==

fetch errors log

paraments:

<nowiki>
{
"command": "logErrors",
"parameters": [
{
"name": "since",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|}

example:

<nowiki>
[
[
"logErrors",
{},
"a2"
]
]

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

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"prefix": "stats",
"text": "Stats client input error: Invalid level",
"timestamp": "Dec 09 16:24:00",
"type": "Error"
},
{
"prefix": "doveadm(127.0.0.1)",
"text": "read(/var/run/dovecot/stats) unexpectedly disconnected",
"timestamp": "Dec 09 16:24:00",
"type": "Fatal"
},
{
"prefix": "stats",
"text": "Stats client input error: Invalid level",
"timestamp": "Dec 09 16:24:22",
"type": "Error"
},
{
"prefix": "stats",
"text": "Stats client input error: Invalid level",
"timestamp": "Dec 09 16:27:48",
"type": "Error"
},
{
"prefix": "director",
"text": "Empty server list",
"timestamp": "Dec 09 16:29:13",
"type": "Error"
},
{
"prefix": "director",
"text": "Invalid value for director_mail_servers setting",
"timestamp": "Dec 09 16:29:13",
"type": "Fatal"
}
],
"a2"
]
]

CLI: doveadm log errors
</nowiki>

== doveadm dict ==
=== doveadm dict get ===

get user key value from configured dictionary

parameters:

<nowiki>
{
"command": "dictGet",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to query
|samik
|-
|dictUri
|String
|optional URI for dictionary to query
|
|-
|key
|String
|key to query
|
|}

=== doveadm dict set ===

set user key value in configured dictionary

parameters:

<nowiki>
{
"command": "dictSet",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
},
{
"name": "value",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|samik
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|key
|String
|dictionary key to modify
|
|-
|value
|string
|value to set
|
|}

=== doveadm dict unset ===

unset user key value in configured dictionary

parameters:

<nowiki>
{
"command": "dictUnset",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|key
|String
|dictionary key to unset
|
|}
== doveadm dict inc ==

increase users key value in dictionary

parameters:

<nowiki>
{
"command": "dictInc",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
},
{
"name": "difference",
"type": "integer"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|-
|key
|String
|dictionary key to increase
|
|}

=== doveadm dict iter ===

list user keys in dictionary

parameters:

<nowiki>
{
"command": "dictIter",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "exact",
"type": "boolean"
},
{
"name": "recurse",
"type": "boolean"
},
{
"name": "noValue",
"type": "boolean"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "prefix",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|exact
|Boolean
|list only exact matches
|
|-
|recurce
|Boolean
|do recursive search
|
|-
|noValue
|Boolean
|list also keys that have no value set
|
|-
|prefix
|String
|search only keys with given prefix
|
|}

== doveadm fs ==
=== doveadm fs get ===

get object from storage

parameters:

<nowiki>
{
"command": "fsGet",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem to fetch
|
|}

=== doveadm fs put ===

put object to storage

parameters:

<nowiki>
{
"command": "fsPut",
"parameters": [
{
"name": "hash",
"type": "string"
},
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "inputPath",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|hash
|string
|
|
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|inputPath
|String
|source object path in local filesystem
|
|-
|path
|String
|object path filesystem to put
|
|}

=== doveadm fs copy ===

copy object in storage

parameters:

<nowiki>
{
"command": "fsCopy",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "sourcePath",
"type": "string"
},
{
"name": "destinationPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|sourcePathh
|String
|source object path
|
|-
|Destination path
|String
|destination object path in filesystem
|
|}

=== doveadm fs stat ===

fetch fs driver statistics

parameters:

<nowiki>
{
"command": "fsStat",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem fetch statistics for
|
|}

=== doveadm fs metadata ===

get filesystem object metadata

parameters:

<nowiki>
{
"command": "fsMetadata",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem fetch statistics for
|
|}

=== doveadm fs delete ===

delete object from storage

<nowiki>
{
"command": "fsDelete",
"parameters": [
{
"name": "recursive",
"type": "boolean"
},
{
"name": "maxParallel",
"type": "integer"
},
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem fetch statistics for
|
|-
|recursive
|Boolean
|do a recursive delete of path
|
|-
|maxParallel
|integer
|max number of parallel workers
|
|}

=== doveadm fs iter ===

list objects in given fs path

parameters:

<nowiki>
{
"command": "fsIter",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|path in filesystem to list
|
|}

=== doveadm fs iter-dirs ===
ist subfolders in given path

parameters:

<nowiki>
{
"command": "fsIterDirs",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|path in filesystem to list for subfolders
|
|}

== doveadm auth cache flush ==

flush authentication cache for one user or all users

parameters:

<nowiki>
{
"command": "authCacheFlush",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String array
|optional list of users in flush
|[“samik”,”samitest”]
|}

example:

<nowiki>
[
[
"authCacheFlush",
{
"user": [
"samik"
]
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["authCacheFlush",{"user":["samik"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"entries": "0"
}
],
"bb"
]
]

CLI: doveadm auth cache flush samik
</nowiki>

== doveadm user ==

do a userdb lookup for an user

<nowiki>
{
"command": "user",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "authInfo",
"type": "array"
},
{
"name": "field",
"type": "string"
},
{
"name": "expandField",
"type": "string"
},
{
"name": "userdbOnly",
"type": "boolean"
},
{
"name": "userMask",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|authInfo
|String array
|auth_info specifies additional conditions for the user command. The auth_info option string has to be given as name=value pair. For multiple conditions the -x option could be supplied multiple times.
Possible names for the auth_info are:
service
The service for which the userdb lookup should be tested. The value may be the name of a service, commonly used with Dovecot. For example: imap, pop3 or smtp.
lip
The local IP address (server) for the test.
rip
The remote IP address (client) for the test.
lport
The local port, e.g. 143
rport
The remote port, e.g. 24567
|sevice=imap
|-
|field
|String
|fetch only one specified field instead of all
|
|-
|expandField
|String
|expand configuration variable with user specific values
|
|-
|userdbOnly
|Boolean
|only fetch from userdb lookup and don’t process passdb
|
|-
|userMask
|String array
|search filter
|
|}

example:

<nowiki>
[
[
"user",
{
"userMask": [
"samik"
]
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["user",{"userMask":["samik"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
{
"samik": {
"gid": "1000",
"home": "/var/vmail/samik",
"junkflag": "0",
"mail": "Maildir:/mails/mails/samik/Maildir",
"namespace/Junk/hidden": "no",
"namespace/Junk/list": "yes",
"uid": "1000"
}
},
"bb"
]
]

CLI: doveadm user samik
</nowiki>

== doveadm mailbox ==
=== doveadm mailbox metadata set ===

set user mailbox metadata

parameters:

<nowiki>
{
"command": "mailboxMetadataSet",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "key",
"type": "string"
},
{
"name": "value",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata set
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to set
|
|-
|value
|String
|metadata value to set
|
|}

example:

<nowiki>
[
[
"mailboxMetadataSet",
{
"key": "/private/comment",
"mailbox": "INBOX",
"user": "samik",
"value": "test"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataSet",{"user":"samik","mailbox":"INBOX","key":"/private/comment","value":"test"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox metadata set –u samik INBOX /private/comment test
</nowiki>

=== doveadm mailbox metadata unset ===

unset user mailbox metadata

parameters:

<nowiki>
{
"command": "mailboxMetadataUnset",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata unset
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to unset
|
|}

example:

<nowiki>
[
[
"mailboxMetadataUnset",
{
"key": "/private/comment",
"mailbox": "INBOX",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataUnset",{"user":"samik","mailbox":"INBOX","key":"/private/comment"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox metadata unset –u samik INBOX /private/comment
</nowiki>

=== doveadm mailbox metadata get ===

get user mailbox metadata

parameters:

<nowiki>
{
"command": "mailboxMetadataGet",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata get
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to get
|
|}

example:

<nowiki>
[
[
"mailboxMetadataGet",
{
"key": "/private/comment",
"mailbox": "INBOX",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataGet",{"user":"samik","mailbox":"INBOX","key":"/private/comment"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response

<nowiki>
[
[
"doveadmResponse",
[
{
"value": "plaa"
}
],
"bb"
]
]

CLI: doveadm mailbox metadata get –u samik INBOX /private/comment
</nowiki>

=== doveadm mailbox list ===

list user mailbox metadata for a folder

parameters:

<nowiki>

"command": "mailboxMetadataList",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "keyPrefix",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata get
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to get
|
|-
|keyPrefix
|String
|search prefix for keys
|
|-
|mailbox
|String
|mailbox to fetch metadata from
|
|}

example:

<nowiki>
[
[
"mailboxMetadataList",
{
"mailbox": "INBOX",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataList",{"user":"samik","mailbox":"INBOX"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"key": "comment"
},
{
"key": "specialuse"
}
],
"bb"
]
]

CLI: doveadm mailbox metadata list –u samik INBOX
</nowiki>

=== doveadm mailbox status ===

fetch user mailbox status

parameters:

<nowiki>
{
"command": "mailboxStatus",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "totalSum",
"type": "boolean"
},
{
"name": "field",
"type": "array"
},
{
"name": "mailboxMask",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply status fetch
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|totalSum
|boolean
|
|
|-
|field
|String array
|fields to fetch
|all
|-
|mailboxMask
|String array
|fetch status on given mailboxes
|
|}

example:

<nowiki>

[
[
"mailboxStatus",
{
"field": [
"all"
],
"mailboxMask": [
"INBOX",
"INBOX/*",
"*"
],
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxStatus",{"user":"samik","field":["all"],"mailboxMask":["INBOX","INBOX/*","*"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"guid": "21b588150b156558eb3500007afd792c",
"highestmodseq": "5",
"mailbox": "Junk",
"messages": "0",
"recent": "0",
"uidnext": "1",
"uidvalidity": "1483019529",
"unseen": "0",
"vsize": "0"
},
{
"guid": "21b588150b156558eb3500007afd792c",
"highestmodseq": "5",
"mailbox": "INBOX",
"messages": "0",
"recent": "0",
"uidnext": "1",
"uidvalidity": "1483019529",
"unseen": "0",
"vsize": "0"
}
],
"bb"
]
]

CLI: doveadm mailbox status –u samik all “*”
</nowiki>

=== doveadm mailbox list ===

fetch user folder list

parameters:

<nowiki>
{
"command": "mailboxList",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mutf7",
"type": "boolean"
},
{
"name": "utf8",
"type": "boolean"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "mailboxMask",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid to apply mailbox list
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|mutf7
|Boolean
|
|
|-
|utf8
|Boolean
|fetch only certain fields instead of all
|
|-
|subscription
|Boolean
|
|
|-
|mailboxMask
|String array
|fetch list of given mailboxes
|
|}

example:

<nowiki>
[
[
"mailboxList",
{
"user": "samik"
},
"bb"
]
]
# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxList",{"user":"samik"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"mailbox": "Junk"
},
{
"mailbox": "INBOX"
}
],
"bb"
]
]

CLI: doveadm mailbox list –u samik
</nowiki>

=== doveadm mailbox create ===
create mailbox folder for user

parameters:

<nowiki>
{
"command": "mailboxCreate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "guid",
"type": "string"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply mailbox create
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|subscription
|Boolean
|
|
|-
|mailbox
|String array
|list of mailbox folders to create
|
|}

example:

<nowiki>
[
[
"mailboxCreate",
{
"mailbox": [
"INBOX/myfolder"
],
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxCreate",{"user":"samik","mailbox":["INBOX/myfolder"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>

[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox create –u samik INBOX/myfolder
</nowiki>

=== doveadm mailbox delete ===

delete user mailbox folder

parameters:

<nowiki>
{
"command": "mailboxDelete",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "requireEmpty",
"type": "boolean"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "recursive",
"type": "boolean"
},
{
"name": "unsafe",
"type": "boolean"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply delete
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|requireEmpty
|Boolean
|only delete if folder is empty
|
|-
|subscription
|Boolean
|
|
|-
|recursive
|Boolean
|delete also subfolders
|
|-
|unsafe
|Boolean
|
|
|-
|mailbox
|String array
|list of mailbox folders to create
|
|}

example:

<nowiki>
[
[
"mailboxDelete",
{
"mailbox": [
"INBOX/myfolder"
],
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxDelete",{"user":"samik","mailbox":["INBOX/myfolder"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox delete –u samik INBOX/myfolder
</nowiki>

=== doveadm mailbox rename ===

rename user folder

parameters:

<nowiki>
{
"command": "mailboxRename",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "newName",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply mailbox rename
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|subscriptions
|Boolean
|
|
|-
|newName
|String
|mailbox new name
|
|-
|mailbox
|String
|mailbox to rename
|
|}

example:

<nowiki>
[
[
"mailboxRename",
{
"mailbox": "INBOX/myfolder",
"newName": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxRename",{"user":"samik","mailbox":"INBOX/myfolder","newName":"INBOX/myfoldertoo"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox rename –u samik INBOX/myfolder INBOX/myfoldertoo
</nowiki>

=== doveadm mailbox subscribe ===

subscribe user to a mailbox

parameters:

<nowiki>
{
"command": "mailboxSubscribe",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply subscribe
|
|-
|userFile
|String
|optionally fetch usernames from. One username per line
|
|-
|mailbox
|String
|mailbox to subscribe
|
|}

example:

<nowiki>
[
[
"mailboxSubscribe",
{
"mailbox": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxSubscribe",{"user":"samik","mailbox":"INBOX/myfoldertoo"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:
<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox subscribe –u samik INBOX/myfoldertoo
</nowiki>

=== doveadm mailbox unsubscribe ===

unsubscribe user from an folder

parameters:

<nowiki>
{
"command": "mailboxUnsubscribe",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply unsubscribe
|
|-
|userFile
|String
|optionally fetch usernames from. One username per line
|
|-
|mailbox
|String
|mailbox to unsubscribe
|
|}

example:

<nowiki>
[
[
"mailboxUnsubscribe",
{
"mailbox": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxUnsubscribe",{"user":"samik","mailbox":"INBOX/myfoldertoo"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox unsubscribe –u samik INBOX/myfoldertoo
</nowiki>

=== doveadm mailbox update ===

update user mailbox information

parameters:

<nowiki>
{
"command": "mailboxUpdate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailboxGuid",
"type": "string"
},
{
"name": "uidValidity",
"type": "string"
},
{
"name": "minNextUid",
"type": "string"
},
{
"name": "minFirstRecentUid",
"type": "string"
},
{
"name": "minHighestModseq",
"type": "string"
},
{
"name": "minHighestPvtModseq",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply update
|
|-
|userFile
|String
|optionally fetch usernames from. One username per line
|
|-
|mailbox
|String
|mailbox to unsubscribe
|
|-
|mailboxGuid
|String
|set mailbox guid
|
|-
|uidValidity
|String
|set mailbox uidvalidity
|
|-
|minNextuid
|String
|set mailbox minimum next uid
|
|-
|minFirstRecentuid
|String
|set mailbox minimum recent uid
|
|-
|minHighestModseq
|String
|
|
|-
|minHighestPvtModseq
|String
|
|
|}

=== doveadm mailbox save ===

save mail into users mailbox

parameters:

<nowiki>
{
"command": "save",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "file",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to save mail into
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|mailbox
|String
|mailbox to unsubscribe
|
|-
|file
|String
|mail to inject
|
|}

example:

<nowiki>
[
[
"save",
{
"file": "From: Joulu Pukki <joulu.pukki@korvatunturi.fi>\nSubject: plaa\n\nmail body\n",
"mailbox": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["save",{"user":"samik","mailbox":"INBOX/myfoldertoo","file":"From: Joulu Pukki <joulu.pukki@korvatunturi.fi>\nSubject: plaa\n\nmail body\n"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]
</nowiki>

== doveadm fetch ==

fetch data from user mailbox

parameters:

<nowiki>
{
"command": "fetch",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "field",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to fetch data
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|field
|String array
|fields to fetch. Supported fields as of dovecot 2.2.26: hdr.<name> body.<section> binary.<section> user mailbox mailbox-guid seq uid guid flags modseq hdr body body.snippet text text.utf8 size.physical size.virtual date.received date.sent date.saved date.received.unixtime date.sent.unixtime date.saved.unixtime imap.envelope imap.body imap.bodystructure pop3.uidl pop3.order refcount storageid
|
|-
|query
|String array
|search query to user
|
|}

example:

<nowiki>
[
[
"fetch",
{
"field": [
"text"
],
"query": [
"mailbox",
"INBOX/myfoldertoo"
],
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["fetch",{"user":"samik","field":["text"],"query":["mailbox","INBOX/myfoldertoo"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"text": "From: Joulu Pukki <joulu.pukki@korvatunturi.fi>\nSubject: plaa\n\nmail body\n"
}
],
"bb"
]
]

CLI: doveadm fetch –u samik “text” mailbox INBOX/myfoldertoo
</nowiki>

== doveadm index ==

index user mailbox folder or folders

parameters:

<nowiki>
{
"command": "index",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "queue",
"type": "boolean"
},
{
"name": "maxRecent",
"type": "string"
},
{
"name": "mailboxMask",
"type": "string"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to index
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|query
|Boolean
|max number of recent mails to index
|
|-
|maxRecent
|String
|max number of recent mails to index
|
|-
|mailboxMask
|String
|mailbox search mask to apply indexing into
|
|}

example:

<nowiki>
[
[
"index",
{
"mailboxMask": "INBOX*",
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["index",{"user":"samik","mailboxMask":"INBOX*"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm index –u samik “INBOX*”
</nowiki>

== doveadm altmove ==

move mails between primary and alternative mailbox storage locations. Applicable to mdbox and sdbox mailbox formats only

parameters:

<nowiki>
{
"command": "altmove",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "reverse",
"type": "boolean"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to apply move
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|reverse
|Boolean
|search query to apply to mail move
|
|-
|query
|String array
|search query to apply to mail move
|
|}

example:

<nowiki>
[
[
"altmove",
{
"query": [
"mailbox",
"INBOX/myfoldertoo",
"savedbefore",
"since",
"30d"
],
"reverse": 0,
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["altmove",{"user":"samik","reverse":0,"query":["mailbox","INBOX/myfoldertoo","savedbefore","since","30d"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

== doveadm deduplicate ==

This command is used to expunge duplicated messages in mailboxes

parameters:

<nowiki>
{
"command": "deduplicate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "byMsgid",
"type": "boolean"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to deduplicate
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|byMsgId
|Boolean
|deduplicate by Message-ID instead of guid
|
|-
|query
|String array
|search query to apply to deduplicate
|
|}

== doveadm expunge ==

Expunge messages matching given search query

parameters:

<nowiki>
{
"command": "expunge",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "deleteEmptyMailbox",
"type": "boolean"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to expunge
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|deleteEmptyMailbox
|Boolean
|delete also mailbox if it’s empty after expunge has been applied
|
|-
|query
|String array
|search query to apply to expunge
|
|}

== doveadm flags ==
add, remove or replace messages' flags

=== doveadm flags add ===

add flag to a message or messages

parameters:

<nowiki>
{
"command": "flagsAdd",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "flag",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to add flags
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|flag
|String array
|list of flags to add
|
|-
|query
|String array
|search query to apply to flag add
|
|}

=== doveadm flags remove ===

remove flags from message or messages

parameters:

<nowiki>
{
"command": "flagsRemove",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "flag",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to add flags
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|flag
|String array
|list of flags to remove
|
|-
|query
|String array
|search query to apply to flag remove
|
|}

=== doveadm flags replace ===

Replace flags with another flag in message or messages. Replaces all current flags with the ones in the parameter list

parameters:

<nowiki>
{
"command": "flagsReplace",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "flag",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to replace flags
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|flag
|String array
|list of flags to replace with
|
|-
|query
|String array
|search query to apply to flag replace
|
|}

== doveadm import ==

Import messages matching given search query

parameters:

<nowiki>
{
"command": "import",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "subscribe",
"type": "boolean"
},
{
"name": "sourceLocation",
"type": "string"
},
{
"name": "destParentMailbox",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to apply import
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|subscribe
|boolean
|when enabled possible newly created folders are also subscibed
|
|-
|sourceLocation
|String
|location of source mailboxes
|
|-
|destParentMailbox
|String
|destination parent mailbox where to import
|
|-
|query
|String array
|search query for messages to import
|
|}

== doveadm force-resync ==

Under certain circumstances it may happen, that dovecot is unable to automatically solve problems with mailboxes. In such situations the force-resync command may be helpful. It tries to fix all problems. For sdbox and mdbox mailboxes the storage files will be also checked.

parameters:

<nowiki>
{
"command": "forceResync",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailboxMask",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|user
|String
|uid of user to apply resync
|
|-
|mailboxMask
|String
|apply forced resync on given mailboxes
|INBOX*
|}

example:

<nowiki>
[
[
"forceResync",
{
"mailboxMask": "INBOX*",
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["forceResync",{"user":"samik","mailboxMask":"INBOX*"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm force-resync –u samik “INBOX*”
</nowiki>

== doveadm purge ==

Remove messages with refcount=0 from mdbox files

parameters:

<nowiki>
{
"command": "purge",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to apply purge
|
|}

== doveadm search ==

Show a list of mailbox GUIDs and message UIDs matching given search query

parameters:

<nowiki>
{
"command": "search",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|user
|String
|uid of user to apply purge
|
|-
|query
|String array
|search query
|
|}

example:

<nowiki>
[
[
"search",
{
"query": [
"mailbox",
"INBOX*",
"all"
],
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["search",{"user":"samik","query":["mailbox","INBOX*","all"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"mailbox-guid": "cf497f128caf7c58612200007afd792c",
"uid": "1"
}
],
"bb"
]
]

CLI: doveadm search –u samik mailbox “INBOX*” all
</nowiki>

== doveadm copy ==

Copy messages matching the given search query into another mailbox

parameters:

<nowiki>
{
"command": "copy",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "destinationMailbox",
"type": "string"
},
{
"name": "sourceType",
"type": "string"
},
{
"name": "sourceUser",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm move ==

Move messages matching the given search query into another mailbox

parameters:

<nowiki>
{
"command": "move",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "destinationMailbox",
"type": "string"
},
{
"name": "sourceType",
"type": "string"
},
{
"name": "sourceUser",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm fscache rescan ==

force fscache rescan

parameters:

<nowiki>
{
"command": "fscacheRescan",
"parameters": [
{
"name": "path",
"type": "string"
},
{
"name": "maxAge",
"type": "integer"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm metacache ==
=== doveadm metacache clean ===

clean metacache content for given user or all users

parameters:

<nowiki>
{

"command": "metacacheClean",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "days",
"type": "integer"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache flush ===

flush metacache contents to storage for given user or all users

parameters:

<nowiki>
{
"command": "metacacheFlush",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache unpack ===

unpack metacache index bundle to target directory

parameters:

<nowiki>
{
"command": "metacacheUnpack",
"parameters": [
{
"name": "bundleName",
"type": "string"
},
{
"name": "bundle",
"type": "string"
},
{
"name": "destinationDirectory",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache flushall ===

flush metacache to storage for all users

parameters:

<nowiki>
{
"command": "metacacheFlushall",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache remove ===

remove metacache for given mask

parameters:

<nowiki>
{
"command": "metacacheRemove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "mask",
"type": "string"
}
]
}
</nowiki>
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache list ===

list local metacache contents

parameters:

<nowiki>
{
"command": "metacacheList",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm obox user delete ==

delete user data from storage, Cassandra and local caches (metacache and fscache).

parameters:

<nowiki>
{
"command": "oboxUserDelete",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

example:

<nowiki>
[
[
"oboxUserDelete",
{
"allUsers": 0,
"socketPath": "",
"user": "testuser003",
"userFile": ""
},
"aa"
]
]

# curl -v -u doveadm:hellodoveadm -X POST http://localhost:ype: application/json" -d '[["oboxUserDelete", {"allUsers":0,"user":"testuser003"}, "aa"]]'
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"aa"
]
]

CLI: doveadm obox user delete –u testuser003
</nowiki>

== doveadm sieve ==

Commands related to handling Sieve scripts.

=== doveadm sieve list ===

list user sieve scripts

parameters:

<nowiki>
{
"command": "sieveList",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve get ===

get user sieve script

parameters:

<nowiki>
{
"command": "sieveGet",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "scriptname",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve put ===

inject sieve script to user

parameters:

<nowiki>
{
"command": "sievePut",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "activate",
"type": "boolean"
},
{
"name": "scriptname",
"type": "string"
},
{
"name": "file",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve delete ===

delete user sieve

parameters:

<nowiki>
{
"command": "sieveDelete",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "ignoreActive",
"type": "boolean"
},
{
"name": "scriptname",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve activate ===

activate user sieve script

parameters:

<nowiki>
{
"command": "sieveActivate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "scriptname",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve deactivate ===

deactivate user sieve

parameters:

<nowiki>
{
"command": "sieveDeactivate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve rename ===

rename user sieve script

parameters:

<nowiki>
{
"command": "sieveRename",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "oldname",
"type": "string"
},
{
"name": "newname",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm fts ==
Dovecot fts indexing commands.

=== doveadm fts lookup ===

query user fts indexed data

parameters:

<nowiki>
{
"command": "ftsLookup",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts expand ===

<nowiki>
{
"command": "ftsExpand",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts tokenize ===

<nowiki>
{
"command": "ftsTokenize",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "language",
"type": "string"
},
{
"name": "text",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts optimize ===

<nowiki>
{
"command": "ftsOptimize",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts rescan ===

<nowiki>
{
"command": "ftsRescan",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

Template:DoveadmHTTPapi

2017-03-15T12:05:57Z

Oskarikentta: /* doveadm director ring remove */

== Table of Contents ==
__TOC__

== 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:

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

=== 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:

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

Basic auth usage:
<nowiki>
curl -H "Authorization: Basic <base64 doveadm:doveadm_password>"
http://host:port/doveadm/v1
</nowiki>
or by letting curl to form the base64 encoded authentication basig authentication header:

<nowiki>
curl –u doveadm:password http://host:port/doveadm/v1
</nowiki>

=== 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:

<nowiki>

[
[
"command1",
{
"parameter1": "value",
"parameter2": "value",
"parameter3": "value"
},
"identifier"
]
]
</nowiki>
Multiple commands can be submitted in one json payload:
<nowiki>
[
[
"command1",
{
"parameter1": "value",
"parameter2": "value"
},
"identifier1"
],
[
"command2",
{
"parameter1": "value",
"parameter2": "value"
},
"identifier2"
]
]
</nowiki>

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:

<nowiki>

son payload:

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

</nowiki>

submitting the command with curl:

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

command line equivalent

doveadm reload

=== successful response ===

<nowiki>

[
[
"doveadmResponse",
[],
"a2"
]
]
</nowiki>

=== failure response ===

<nowiki>

[
[
"error",
{
"exitCode": 68,
"type": "exitCode"
},
"a2"
]
</nowiki>

=== failure codes ===

{| class="wikitable"
|-
|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
|}

== Supported commands ==

== doveadm service ==
=== doveadm service stop ===

stop one or more dovecot services on target host

<nowiki>
{
"command": "serviceStop",
"parameters": [
{
"name": "service",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|service
|string array
|Name of service to stop
|[“imap”,”imap-hibernate”]
|}

example:

<nowiki>
[
[
"serviceStop",
{
"service": [
"imap",
"imap-hibernate"
]
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["serviceStop",{"service":["imap","imap-hibernate"]},"aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm service stop imap imap-hibernate
</nowiki>

=== doveadm stop ===

stop dovecot on the target host
<nowiki>

{
"command": "stop",
"parameters": []
}

no parameters
</nowiki>
example:
<nowiki>
[
[
"stop",
{},
"a1"
]
]

# curl -u doveadm:hellodoveadm -X POST http://localhost:8080/doveadm/v1 -H "Content-Type: application/json" -d '[["stop",{},"a1"]]'

CLI: doveadm stop
</nowiki>

=== doveadm reload ===

reload dovecot configuration

<nowiki>
{
"command": "reload",
"parameters": []
}
</nowiki>

example:

<nowiki>
[
[
"reload",
{},
"a2"
]
]

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

CLI: doveadm reload
</nowiki>

== doveadm stats ==
=== doveadm stats dump ===

dump collected dovecot statistics

<nowiki>
{
"command": "statsDump",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "type",
"type": "string"
},
{
"name": "filter",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|+parameters
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|type
|String
|Type of stats to dump
|global
|-
|filter
|String
|Dump filter
|last_update 1483101542
|}

Example:

<nowiki>
[
[
"statsDump",
{
"type": "global"
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["statsDump",{"type":"global"},"aa"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"auth_cache_hits": "0",
"auth_cache_misses": "0",
"auth_db_tempfails": "0",
"auth_failures": "0",
"auth_master_successes": "0",
"auth_successes": "0",
"clock_time": "0.0",
"disk_input": "0",
"disk_output": "0",
"fscache_read": "0",
"fscache_stat": "0",
"fscache_write": "0",
"idx_del": "0",
"idx_iter": "0",
"idx_read": "0",
"idx_read_usecs": "0",
"idx_wbytes": "0",
"idx_write": "0",
"idx_write_usecs": "0",
"invol_cs": "0",
"last_update": "0.000000",
"mail_cache_hits": "0",
"mail_lookup_attr": "0",
"mail_lookup_path": "0",
"mail_read_bytes": "0",
"mail_read_count": "0",
"maj_faults": "0",
"min_faults": "0",
"num_cmds": "0",
"num_connected_sessions": "0",
"num_logins": "0",
"obox_copy": "0",
"obox_del": "0",
"obox_iter": "0",
"obox_read": "0",
"obox_read_usecs": "0",
"obox_stat": "0",
"obox_wbytes": "0",
"obox_write": "0",
"obox_write_usecs": "0",
"read_bytes": "0",
"read_count": "0",
"reset_timestamp": "1483104199",
"sys_cpu": "0.0",
"user_cpu": "0.0",
"vol_cs": "0",
"write_bytes": "0",
"write_count": "0"
}
],
"aa"
]
]

CLI: doveadm stats dump global
</nowiki>

=== doveadm stats reset ===
reset dovecot statistics counters
<nowiki>

{
"command": "statsReset",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|}

example:

<nowiki>
[
[
"statsReset",
{},
"aa"
]
]

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

CLI: doveadm stats reset
</nowiki>

== doveadm penalty ==

<nowiki>
show current penalties

{
"command": "penalty",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "netmask",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|string
|Path to doveadm socket
|/var/run/dovecot-server
|-
|netmask
|string
|To reduce/filter the output supply an IP address or a network range in CIDR notation (ip/mask)
|10.0.0.0/24
|}

example:

<nowiki>
[
[
"penalty",
{},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["penalty",{},"aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm penalty
</nowiki>

== doveadm kick ==

Kick user from dovecot. Applicable to session in dovecot backend only

<nowiki>
{
"command": "kick",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "force",
"type": "boolean"
},
{
"name": "mask",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|force
|Boolean
|Do a forced kick?
|0
|-
|mask
|String
|Uid mask
|testuser001
|}

example:

<nowiki>
[
[
"kick",
{
"force": 0,
"mask": "testuser001"
},
"aa"
]
]

# curl -v -u doveadm:hellodoveadm –H “Content-Type: application/json" -d '[["kick", {"mask":"testuser001"}, "aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm kick testuser001
</nowiki>

response for succesfull kick:

<nowiki>
[
[
"doveadmResponse",
[
{
"result": "testuser001"
}
],
"aa"
]
]
</nowiki>

response in case kick failed:

<nowiki>
[
[
"error",
{
"exitCode": 68,
"type": "exitCode"
},
"aa"
]
]
</nowiki>

== doveadm who ==

<nowiki>
list active dovecot sessions

{
"command": "who",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "separateConnections",
"type": "boolean"
},
{
"name": "mask",
"type": "array"
}
]
}
</nowiki>

parameters

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|string
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|separateConnections
|Boolean
|Show each user connection in separate entries
|0
|-
|mask
|string array
|Uid mask
|testuser001
|}

Example:

<nowiki>
[
[
"who",
{
"mask": "",
"separateConnections": 0,
"socketPath": ""
},
"aa"
]
]

# curl -v -u doveadm:hellodoveadm -X POST http://localhost:ype: application/json" -d '[["who", {}, "aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm who
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"connections": "1",
"ips": "(127.0.0.1)",
"pids": "(4999)",
"service": "imap",
"username": "testuser001"
}
],
"aa"
]
]
</nowiki>

== doveadm director ==
=== doveadm director status ===

Show backend statuses on directors. Available only in directors

<nowiki>
[
{
"command": "directorStatus",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "tag",
"type": "string"
}
]
}
]
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|String
|Show director status for Tagged hosts only
|NewBackend
|}

example:

<nowiki>
[
[
"directorStatus",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorStatus",{},"bb"]]' http://localhost:8080/doveadm/v1

</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"mail server ip": "10.0.0.234",
"state": "up",
"state-changed": "2016-12-15 08:31:37",
"tag": "",
"users": "1",
"vhosts": "100"
},
{
"mail server ip": "10.0.0.235",
"state": "up",
"state-changed": "2016-12-15 08:31:04",
"tag": "",
"users": "0",
"vhosts": "100"
}
],
"bb"
]
]

CLI: doveadm director status
</nowiki>

=== doveadm director map ===

list current user → host mappings. Applicable to director only

<nowiki>

"command": "directorMap",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "usersFile",
"type": "string"
},
{
"name": "hashMap",
"type": "boolean"
},
{
"name": "userMap",
"type": "boolean"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

parameters

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|usersFile
|String
|provide Path to users list. One username per line
|/etc/dovecot/userlist.txt
|-
|hashMap
|Boolean
|Output users as hashmap
|True
|-
|userMap
|Boolean
|Output users as userlist
|True
|-
|host
|String
|Show only mappings to given host
|10.0.0.234
|}

example:

<nowiki>
[
[
"directorMap",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorMap",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"expire time": "2016-12-30 14:52:56",
"hash": "3853430566",
"mail server ip": "10.0.0.235",
"user": "samik"
}
],
"bb"
]
]

CLI: doveadm director map
</nowiki>

=== doveadm director add ===

add backend to director ring

<nowiki>
{
"command": "directorAdd",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "tag",
"type": "string"
},
{
"name": "host",
"type": "string"
},
{
"name": "vhostCount",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|tag
|String
|apply tag to backend
|/etc/dovecot/userlist.txt
|-
|host
|String
|backend ip to add
|10.0.0.234
|-
|vhostCount
|String
|vhost count to add
|100
|}

Example:

<nowiki>
[
[
"directorAdd",
{
"host": "10.0.234"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorAdd",{"host":"10.0.234"},"bb"]]' http://localhost:8080/doveadm/v1

CLI: doveadm director add 10.0.0.234
</nowiki>

=== doveadm director update ===

<nowiki>
{
"command": "directorUpdate",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
},
{
"name": "vhostCount",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|string
|Show director status for tagged hosts only
|NewBackend
|}

=== doveadm director up ===

<nowiki>
{
"command": "directorUp",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|string
|Show director status for tagged hosts only
|NewBackend
|}

=== doveadm director down ===

<nowiki>
{
"command": "directorDown",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|string
|Show director status for tagged hosts only
|NewBackend
|}

=== doveadm director remove ===

remove backend from director ring

<nowiki>
{
"command": "directorRemove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|host
|String
|backend to remove
|10.0.0.134
|}

example:

<nowiki>
[
[
"directorRemove",
{
"host": "10.0.0.234"
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRemove",{"host":"10.0.0.234"},"aa"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"aa"
]
]

CLI: doveadm director remove 10.0.0.234
</nowiki>

=== doveadm director move ===

move user mapping from backend to another or create director mapping for an user
<nowiki>
{
"command": "directorMove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|user
|String
|User uid to move
|testuser001
|-
|host
|string
|Target backend ip as listed in doveadm doveadm director status
|10.0.0.234
|}

example:

<nowiki>
[
[
"directorMove",
{
"host": "10.0.234",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorMove",{"user":"samik","host":"10.0.234"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director move samik 10.0.0.234
</nowiki>

== doveadm director kick ==

<nowiki>
{
"command": "directorKick",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|user
|String
|uid of user to kick
|samik
|}

example:

<nowiki>
[
[
"directorKick",
{
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorKick",{"user":"samik"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director kick samik
</nowiki>

=== doveadm director flush ===

flush connection mappings to one backend at director level. All users mapped to given host will be flushed from the hashmap table and will be redistributed to backends.

Parameters:

<nowiki>
{
"command": "directorFlush",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "forceFlush",
"type": "boolean"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|forceFlush
|Boolean
|Flag to make flush forced
|True
|-
|host
|String
|Backend ip address from doveadm director status list
|10.0.0.234
|}

example:

<nowiki>
[
[
"directorFlush",
{
"host": "10.0.0.234"
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorFlush",{"host":"10.0.0.234"},"aa"]]' http://localhost:8080/doveadm/v1

</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"aa"
]
]
CLI: doveadm director flush 10.0.234
</nowiki>

=== doveadm director dump ===

Dumb the current director backend host configuration as commands

<nowiki>
{
"command": "directorDump",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|}

example:

<nowiki>
[
[
"directorDump",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorDump",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"command": "add",
"host": "10.0.0.234",
"socket-path": "/var/run/dovecot/director-admin",
"vhost_count": "100"
},
{
"command": "add",
"host": "10.0.0.235",
"socket-path": "/var/run/dovecot/director-admin",
"vhost_count": "100"
}
],
"bb"
]
]

CLI: doveadm director dump
</nowiki>

=== doveadm director ring add ===

add new director to director ring

parameters:

<nowiki>
{
"command": "directorRingAdd",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "ip",
"type": "string"
},
{
"name": "port",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|ip
|String
|director ip address to add
|10.0.0.233
|-
|port
|String
|port number to use if not default
|9143
|}

example:

<nowiki>
[
[
"directorRingAdd",
{
"ip": "10.0.0.233"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRingAdd",{"ip":"10.0.0.233"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director ring add 10.0.0.233
</nowiki>

=== doveadm director ring remove ===

remove director from director ring

parameters:

<nowiki>
{
"command": "directorRingRemove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "ip",
"type": "string"
},
{
"name": "port",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|ip
|String
|director ip to remove
|10.0.0.233
|-
|port
|String
|director service port if not default
|9143
|}

example:

<nowiki>
[
[
"directorRingRemove",
{
"ip": "10.0.0.233"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRingRemove",{"ip":"10.0.0.233"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director ring remove 10.0.0.233
</nowiki>

=== doveadm director ring status ===

show director ring status

parameters:

<nowiki>

{
"command": "directorRingStatus",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|}

example:

<nowiki>
[
[
"directorRingStatus",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRingStatus",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>

[
"doveadmResponse",
[
{
"director ip": "10.0.0.232",
"last failed": "never",
"port": "9143",
"status": "synced",
"type": "self"
},
{
"director ip": "10.0.0.233",
"last failed": "never",
"port": "9143",
"status": "",
"type": ""
}
],
"bb"
]
]

CLI: doveadm director ring status
</nowiki>

== doveadm proxy ==

The doveadm proxy commands are used to list or kick active Dovecot proxy connections.

=== doveadm proxy list ===

list active connections in the dovecot proxy

parameters:

<nowiki>
{
"command": "proxyList",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|}

example:

<nowiki>
[
[
"proxyList",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["proxyList",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"dest-ip": "127.0.0.1",
"dest-port": "1143",
"service": "imap",
"src-ip": "10.0.0.153",
"username": "samik"
}
],
"bb"
]
]

CLI: doveadm proxy list
</nowiki>

=== doveadm proxy kick ===

kick user session from proxy. applicable to imap/pop3/managesieve sessions

parameters:

<nowiki>
{
"command": "proxyKick",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|userid to kick
|samik
|}

example:

<nowiki>
[
[
"proxyKick",
{
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["proxyKick",{"user":"samik"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"count": "1"
}
],
"bb"
]
]

CLI: doveadm proxy kick samik
</nowiki>

== doveadm logs errors ==

fetch errors log

paraments:

<nowiki>
{
"command": "logErrors",
"parameters": [
{
"name": "since",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|}

example:

<nowiki>
[
[
"logErrors",
{},
"a2"
]
]

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

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"prefix": "stats",
"text": "Stats client input error: Invalid level",
"timestamp": "Dec 09 16:24:00",
"type": "Error"
},
{
"prefix": "doveadm(127.0.0.1)",
"text": "read(/var/run/dovecot/stats) unexpectedly disconnected",
"timestamp": "Dec 09 16:24:00",
"type": "Fatal"
},
{
"prefix": "stats",
"text": "Stats client input error: Invalid level",
"timestamp": "Dec 09 16:24:22",
"type": "Error"
},
{
"prefix": "stats",
"text": "Stats client input error: Invalid level",
"timestamp": "Dec 09 16:27:48",
"type": "Error"
},
{
"prefix": "director",
"text": "Empty server list",
"timestamp": "Dec 09 16:29:13",
"type": "Error"
},
{
"prefix": "director",
"text": "Invalid value for director_mail_servers setting",
"timestamp": "Dec 09 16:29:13",
"type": "Fatal"
}
],
"a2"
]
]

CLI: doveadm log errors
</nowiki>

== doveadm dict ==
=== doveadm dict get ===

get user key value from configured dictionary

parameters:

<nowiki>
{
"command": "dictGet",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to query
|samik
|-
|dictUri
|String
|optional URI for dictionary to query
|
|-
|key
|String
|key to query
|
|}

=== doveadm dict set ===

set user key value in configured dictionary

parameters:

<nowiki>
{
"command": "dictSet",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
},
{
"name": "value",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|samik
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|key
|String
|dictionary key to modify
|
|-
|value
|string
|value to set
|
|}

=== doveadm dict unset ===

unset user key value in configured dictionary

parameters:

<nowiki>
{
"command": "dictUnset",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|key
|String
|dictionary key to unset
|
|}
== doveadm dict inc ==

increase users key value in dictionary

parameters:

<nowiki>
{
"command": "dictInc",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
},
{
"name": "difference",
"type": "integer"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|optional URI for dictionary to modify
|
|-
|key
|String
|dictionary key to increase
|
|-
|difference
|integer
|increment value
|
|}

=== doveadm dict iter ===

list user keys in dictionary

parameters:

<nowiki>
{
"command": "dictIter",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "exact",
"type": "boolean"
},
{
"name": "recurse",
"type": "boolean"
},
{
"name": "noValue",
"type": "boolean"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "prefix",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|exact
|Boolean
|list only exact matches
|
|-
|recurce
|Boolean
|do recursive search
|
|-
|noValue
|Boolean
|list also keys that have no value set
|
|-
|prefix
|String
|search only keys with given prefix
|
|}

== doveadm fs ==
=== doveadm fs get ===

get object from storage

parameters:

<nowiki>
{
"command": "fsGet",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem to fetch
|
|}

=== doveadm fs put ===

put object to storage

parameters:

<nowiki>
{
"command": "fsPut",
"parameters": [
{
"name": "hash",
"type": "string"
},
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "inputPath",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|hash
|string
|
|
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|inputPath
|String
|source object path in local filesystem
|
|-
|path
|String
|object path filesystem to put
|
|}

=== doveadm fs copy ===

copy object in storage

parameters:

<nowiki>
{
"command": "fsCopy",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "sourcePath",
"type": "string"
},
{
"name": "destinationPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|sourcePathh
|String
|source object path
|
|-
|Destination path
|String
|destination object path in filesystem
|
|}

=== doveadm fs stat ===

fetch fs driver statistics

parameters:

<nowiki>
{
"command": "fsStat",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem fetch statistics for
|
|}

=== doveadm fs metadata ===

get filesystem object metadata

parameters:

<nowiki>
{
"command": "fsMetadata",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem fetch statistics for
|
|}

=== doveadm fs delete ===

delete object from storage

<nowiki>
{
"command": "fsDelete",
"parameters": [
{
"name": "recursive",
"type": "boolean"
},
{
"name": "maxParallel",
"type": "integer"
},
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem fetch statistics for
|
|-
|recursive
|Boolean
|do a recursive delete of path
|
|-
|maxParallel
|integer
|max number of parallel workers
|
|}

=== doveadm fs iter ===

list objects in given fs path

parameters:

<nowiki>
{
"command": "fsIter",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|path in filesystem to list
|
|}

=== doveadm fs iter-dirs ===
ist subfolders in given path

parameters:

<nowiki>
{
"command": "fsIterDirs",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|path in filesystem to list for subfolders
|
|}

== doveadm auth cache flush ==

flush authentication cache for one user or all users

parameters:

<nowiki>
{
"command": "authCacheFlush",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String array
|optional list of users in flush
|[“samik”,”samitest”]
|}

example:

<nowiki>
[
[
"authCacheFlush",
{
"user": [
"samik"
]
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["authCacheFlush",{"user":["samik"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"entries": "0"
}
],
"bb"
]
]

CLI: doveadm auth cache flush samik
</nowiki>

== doveadm user ==

do a userdb lookup for an user

<nowiki>
{
"command": "user",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "authInfo",
"type": "array"
},
{
"name": "field",
"type": "string"
},
{
"name": "expandField",
"type": "string"
},
{
"name": "userdbOnly",
"type": "boolean"
},
{
"name": "userMask",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|authInfo
|String array
|auth_info specifies additional conditions for the user command. The auth_info option string has to be given as name=value pair. For multiple conditions the -x option could be supplied multiple times.
Possible names for the auth_info are:
service
The service for which the userdb lookup should be tested. The value may be the name of a service, commonly used with Dovecot. For example: imap, pop3 or smtp.
lip
The local IP address (server) for the test.
rip
The remote IP address (client) for the test.
lport
The local port, e.g. 143
rport
The remote port, e.g. 24567
|sevice=imap
|-
|field
|String
|fetch only one specified field instead of all
|
|-
|expandField
|String
|expand configuration variable with user specific values
|
|-
|userdbOnly
|Boolean
|only fetch from userdb lookup and don’t process passdb
|
|-
|userMask
|String array
|search filter
|
|}

example:

<nowiki>
[
[
"user",
{
"userMask": [
"samik"
]
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["user",{"userMask":["samik"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
{
"samik": {
"gid": "1000",
"home": "/var/vmail/samik",
"junkflag": "0",
"mail": "Maildir:/mails/mails/samik/Maildir",
"namespace/Junk/hidden": "no",
"namespace/Junk/list": "yes",
"uid": "1000"
}
},
"bb"
]
]

CLI: doveadm user samik
</nowiki>

== doveadm mailbox ==
=== doveadm mailbox metadata set ===

set user mailbox metadata

parameters:

<nowiki>
{
"command": "mailboxMetadataSet",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "key",
"type": "string"
},
{
"name": "value",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata set
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to set
|
|-
|value
|String
|metadata value to set
|
|}

example:

<nowiki>
[
[
"mailboxMetadataSet",
{
"key": "/private/comment",
"mailbox": "INBOX",
"user": "samik",
"value": "test"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataSet",{"user":"samik","mailbox":"INBOX","key":"/private/comment","value":"test"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox metadata set –u samik INBOX /private/comment test
</nowiki>

=== doveadm mailbox metadata unset ===

unset user mailbox metadata

parameters:

<nowiki>
{
"command": "mailboxMetadataUnset",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata unset
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to unset
|
|}

example:

<nowiki>
[
[
"mailboxMetadataUnset",
{
"key": "/private/comment",
"mailbox": "INBOX",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataUnset",{"user":"samik","mailbox":"INBOX","key":"/private/comment"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox metadata unset –u samik INBOX /private/comment
</nowiki>

=== doveadm mailbox metadata get ===

get user mailbox metadata

parameters:

<nowiki>
{
"command": "mailboxMetadataGet",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata get
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to get
|
|}

example:

<nowiki>
[
[
"mailboxMetadataGet",
{
"key": "/private/comment",
"mailbox": "INBOX",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataGet",{"user":"samik","mailbox":"INBOX","key":"/private/comment"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response

<nowiki>
[
[
"doveadmResponse",
[
{
"value": "plaa"
}
],
"bb"
]
]

CLI: doveadm mailbox metadata get –u samik INBOX /private/comment
</nowiki>

=== doveadm mailbox list ===

list user mailbox metadata for a folder

parameters:

<nowiki>

"command": "mailboxMetadataList",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "keyPrefix",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata get
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to get
|
|-
|keyPrefix
|String
|search prefix for keys
|
|-
|mailbox
|String
|mailbox to fetch metadata from
|
|}

example:

<nowiki>
[
[
"mailboxMetadataList",
{
"mailbox": "INBOX",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataList",{"user":"samik","mailbox":"INBOX"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"key": "comment"
},
{
"key": "specialuse"
}
],
"bb"
]
]

CLI: doveadm mailbox metadata list –u samik INBOX
</nowiki>

=== doveadm mailbox status ===

fetch user mailbox status

parameters:

<nowiki>
{
"command": "mailboxStatus",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "totalSum",
"type": "boolean"
},
{
"name": "field",
"type": "array"
},
{
"name": "mailboxMask",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply status fetch
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|totalSum
|boolean
|
|
|-
|field
|String array
|fields to fetch
|all
|-
|mailboxMask
|String array
|fetch status on given mailboxes
|
|}

example:

<nowiki>

[
[
"mailboxStatus",
{
"field": [
"all"
],
"mailboxMask": [
"INBOX",
"INBOX/*",
"*"
],
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxStatus",{"user":"samik","field":["all"],"mailboxMask":["INBOX","INBOX/*","*"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"guid": "21b588150b156558eb3500007afd792c",
"highestmodseq": "5",
"mailbox": "Junk",
"messages": "0",
"recent": "0",
"uidnext": "1",
"uidvalidity": "1483019529",
"unseen": "0",
"vsize": "0"
},
{
"guid": "21b588150b156558eb3500007afd792c",
"highestmodseq": "5",
"mailbox": "INBOX",
"messages": "0",
"recent": "0",
"uidnext": "1",
"uidvalidity": "1483019529",
"unseen": "0",
"vsize": "0"
}
],
"bb"
]
]

CLI: doveadm mailbox status –u samik all “*”
</nowiki>

=== doveadm mailbox list ===

fetch user folder list

parameters:

<nowiki>
{
"command": "mailboxList",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mutf7",
"type": "boolean"
},
{
"name": "utf8",
"type": "boolean"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "mailboxMask",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid to apply mailbox list
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|mutf7
|Boolean
|
|
|-
|utf8
|Boolean
|fetch only certain fields instead of all
|
|-
|subscription
|Boolean
|
|
|-
|mailboxMask
|String array
|fetch list of given mailboxes
|
|}

example:

<nowiki>
[
[
"mailboxList",
{
"user": "samik"
},
"bb"
]
]
# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxList",{"user":"samik"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"mailbox": "Junk"
},
{
"mailbox": "INBOX"
}
],
"bb"
]
]

CLI: doveadm mailbox list –u samik
</nowiki>

=== doveadm mailbox create ===
create mailbox folder for user

parameters:

<nowiki>
{
"command": "mailboxCreate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "guid",
"type": "string"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply mailbox create
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|subscription
|Boolean
|
|
|-
|mailbox
|String array
|list of mailbox folders to create
|
|}

example:

<nowiki>
[
[
"mailboxCreate",
{
"mailbox": [
"INBOX/myfolder"
],
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxCreate",{"user":"samik","mailbox":["INBOX/myfolder"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>

[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox create –u samik INBOX/myfolder
</nowiki>

=== doveadm mailbox delete ===

delete user mailbox folder

parameters:

<nowiki>
{
"command": "mailboxDelete",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "requireEmpty",
"type": "boolean"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "recursive",
"type": "boolean"
},
{
"name": "unsafe",
"type": "boolean"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply delete
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|requireEmpty
|Boolean
|only delete if folder is empty
|
|-
|subscription
|Boolean
|
|
|-
|recursive
|Boolean
|delete also subfolders
|
|-
|unsafe
|Boolean
|
|
|-
|mailbox
|String array
|list of mailbox folders to create
|
|}

example:

<nowiki>
[
[
"mailboxDelete",
{
"mailbox": [
"INBOX/myfolder"
],
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxDelete",{"user":"samik","mailbox":["INBOX/myfolder"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox delete –u samik INBOX/myfolder
</nowiki>

=== doveadm mailbox rename ===

rename user folder

parameters:

<nowiki>
{
"command": "mailboxRename",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "newName",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply mailbox rename
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|subscriptions
|Boolean
|
|
|-
|newName
|String
|mailbox new name
|
|-
|mailbox
|String
|mailbox to rename
|
|}

example:

<nowiki>
[
[
"mailboxRename",
{
"mailbox": "INBOX/myfolder",
"newName": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxRename",{"user":"samik","mailbox":"INBOX/myfolder","newName":"INBOX/myfoldertoo"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox rename –u samik INBOX/myfolder INBOX/myfoldertoo
</nowiki>

=== doveadm mailbox subscribe ===

subscribe user to a mailbox

parameters:

<nowiki>
{
"command": "mailboxSubscribe",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply subscribe
|
|-
|userFile
|String
|optionally fetch usernames from. One username per line
|
|-
|mailbox
|String
|mailbox to subscribe
|
|}

example:

<nowiki>
[
[
"mailboxSubscribe",
{
"mailbox": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxSubscribe",{"user":"samik","mailbox":"INBOX/myfoldertoo"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:
<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox subscribe –u samik INBOX/myfoldertoo
</nowiki>

=== doveadm mailbox unsubscribe ===

unsubscribe user from an folder

parameters:

<nowiki>
{
"command": "mailboxUnsubscribe",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply unsubscribe
|
|-
|userFile
|String
|optionally fetch usernames from. One username per line
|
|-
|mailbox
|String
|mailbox to unsubscribe
|
|}

example:

<nowiki>
[
[
"mailboxUnsubscribe",
{
"mailbox": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxUnsubscribe",{"user":"samik","mailbox":"INBOX/myfoldertoo"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox unsubscribe –u samik INBOX/myfoldertoo
</nowiki>

=== doveadm mailbox update ===

update user mailbox information

parameters:

<nowiki>
{
"command": "mailboxUpdate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailboxGuid",
"type": "string"
},
{
"name": "uidValidity",
"type": "string"
},
{
"name": "minNextUid",
"type": "string"
},
{
"name": "minFirstRecentUid",
"type": "string"
},
{
"name": "minHighestModseq",
"type": "string"
},
{
"name": "minHighestPvtModseq",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply update
|
|-
|userFile
|String
|optionally fetch usernames from. One username per line
|
|-
|mailbox
|String
|mailbox to unsubscribe
|
|-
|mailboxGuid
|String
|set mailbox guid
|
|-
|uidValidity
|String
|set mailbox uidvalidity
|
|-
|minNextuid
|String
|set mailbox minimum next uid
|
|-
|minFirstRecentuid
|String
|set mailbox minimum recent uid
|
|-
|minHighestModseq
|String
|
|
|-
|minHighestPvtModseq
|String
|
|
|}

=== doveadm mailbox save ===

save mail into users mailbox

parameters:

<nowiki>
{
"command": "save",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "file",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to save mail into
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|mailbox
|String
|mailbox to unsubscribe
|
|-
|file
|String
|mail to inject
|
|}

example:

<nowiki>
[
[
"save",
{
"file": "From: Joulu Pukki <joulu.pukki@korvatunturi.fi>\nSubject: plaa\n\nmail body\n",
"mailbox": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["save",{"user":"samik","mailbox":"INBOX/myfoldertoo","file":"From: Joulu Pukki <joulu.pukki@korvatunturi.fi>\nSubject: plaa\n\nmail body\n"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]
</nowiki>

== doveadm fetch ==

fetch data from user mailbox

parameters:

<nowiki>
{
"command": "fetch",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "field",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to fetch data
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|field
|String array
|fields to fetch. Supported fields as of dovecot 2.2.26: hdr.<name> body.<section> binary.<section> user mailbox mailbox-guid seq uid guid flags modseq hdr body body.snippet text text.utf8 size.physical size.virtual date.received date.sent date.saved date.received.unixtime date.sent.unixtime date.saved.unixtime imap.envelope imap.body imap.bodystructure pop3.uidl pop3.order refcount storageid
|
|-
|query
|String array
|search query to user
|
|}

example:

<nowiki>
[
[
"fetch",
{
"field": [
"text"
],
"query": [
"mailbox",
"INBOX/myfoldertoo"
],
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["fetch",{"user":"samik","field":["text"],"query":["mailbox","INBOX/myfoldertoo"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"text": "From: Joulu Pukki <joulu.pukki@korvatunturi.fi>\nSubject: plaa\n\nmail body\n"
}
],
"bb"
]
]

CLI: doveadm fetch –u samik “text” mailbox INBOX/myfoldertoo
</nowiki>

== doveadm index ==

index user mailbox folder or folders

parameters:

<nowiki>
{
"command": "index",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "queue",
"type": "boolean"
},
{
"name": "maxRecent",
"type": "string"
},
{
"name": "mailboxMask",
"type": "string"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to index
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|query
|Boolean
|max number of recent mails to index
|
|-
|maxRecent
|String
|max number of recent mails to index
|
|-
|mailboxMask
|String
|mailbox search mask to apply indexing into
|
|}

example:

<nowiki>
[
[
"index",
{
"mailboxMask": "INBOX*",
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["index",{"user":"samik","mailboxMask":"INBOX*"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm index –u samik “INBOX*”
</nowiki>

== doveadm altmove ==

move mails between primary and alternative mailbox storage locations. Applicable to mdbox and sdbox mailbox formats only

parameters:

<nowiki>
{
"command": "altmove",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "reverse",
"type": "boolean"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to apply move
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|reverse
|Boolean
|search query to apply to mail move
|
|-
|query
|String array
|search query to apply to mail move
|
|}

example:

<nowiki>
[
[
"altmove",
{
"query": [
"mailbox",
"INBOX/myfoldertoo",
"savedbefore",
"since",
"30d"
],
"reverse": 0,
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["altmove",{"user":"samik","reverse":0,"query":["mailbox","INBOX/myfoldertoo","savedbefore","since","30d"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

== doveadm deduplicate ==

This command is used to expunge duplicated messages in mailboxes

parameters:

<nowiki>
{
"command": "deduplicate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "byMsgid",
"type": "boolean"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to deduplicate
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|byMsgId
|Boolean
|deduplicate by Message-ID instead of guid
|
|-
|query
|String array
|search query to apply to deduplicate
|
|}

== doveadm expunge ==

Expunge messages matching given search query

parameters:

<nowiki>
{
"command": "expunge",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "deleteEmptyMailbox",
"type": "boolean"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to expunge
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|deleteEmptyMailbox
|Boolean
|delete also mailbox if it’s empty after expunge has been applied
|
|-
|query
|String array
|search query to apply to expunge
|
|}

== doveadm flags ==
add, remove or replace messages' flags

=== doveadm flags add ===

add flag to a message or messages

parameters:

<nowiki>
{
"command": "flagsAdd",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "flag",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to add flags
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|flag
|String array
|list of flags to add
|
|-
|query
|String array
|search query to apply to flag add
|
|}

=== doveadm flags remove ===

remove flags from message or messages

parameters:

<nowiki>
{
"command": "flagsRemove",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "flag",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to add flags
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|flag
|String array
|list of flags to remove
|
|-
|query
|String array
|search query to apply to flag remove
|
|}

=== doveadm flags replace ===

Replace flags with another flag in message or messages. Replaces all current flags with the ones in the parameter list

parameters:

<nowiki>
{
"command": "flagsReplace",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "flag",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to replace flags
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|flag
|String array
|list of flags to replace with
|
|-
|query
|String array
|search query to apply to flag replace
|
|}

== doveadm import ==

Import messages matching given search query

parameters:

<nowiki>
{
"command": "import",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "subscribe",
"type": "boolean"
},
{
"name": "sourceLocation",
"type": "string"
},
{
"name": "destParentMailbox",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to apply import
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|subscribe
|boolean
|when enabled possible newly created folders are also subscibed
|
|-
|sourceLocation
|String
|location of source mailboxes
|
|-
|destParentMailbox
|String
|destination parent mailbox where to import
|
|-
|query
|String array
|search query for messages to import
|
|}

== doveadm force-resync ==

Under certain circumstances it may happen, that dovecot is unable to automatically solve problems with mailboxes. In such situations the force-resync command may be helpful. It tries to fix all problems. For sdbox and mdbox mailboxes the storage files will be also checked.

parameters:

<nowiki>
{
"command": "forceResync",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailboxMask",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|user
|String
|uid of user to apply resync
|
|-
|mailboxMask
|String
|apply forced resync on given mailboxes
|INBOX*
|}

example:

<nowiki>
[
[
"forceResync",
{
"mailboxMask": "INBOX*",
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["forceResync",{"user":"samik","mailboxMask":"INBOX*"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm force-resync –u samik “INBOX*”
</nowiki>

== doveadm purge ==

Remove messages with refcount=0 from mdbox files

parameters:

<nowiki>
{
"command": "purge",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to apply purge
|
|}

== doveadm search ==

Show a list of mailbox GUIDs and message UIDs matching given search query

parameters:

<nowiki>
{
"command": "search",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|user
|String
|uid of user to apply purge
|
|-
|query
|String array
|search query
|
|}

example:

<nowiki>
[
[
"search",
{
"query": [
"mailbox",
"INBOX*",
"all"
],
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["search",{"user":"samik","query":["mailbox","INBOX*","all"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"mailbox-guid": "cf497f128caf7c58612200007afd792c",
"uid": "1"
}
],
"bb"
]
]

CLI: doveadm search –u samik mailbox “INBOX*” all
</nowiki>

== doveadm copy ==

Copy messages matching the given search query into another mailbox

parameters:

<nowiki>
{
"command": "copy",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "destinationMailbox",
"type": "string"
},
{
"name": "sourceType",
"type": "string"
},
{
"name": "sourceUser",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm move ==

Move messages matching the given search query into another mailbox

parameters:

<nowiki>
{
"command": "move",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "destinationMailbox",
"type": "string"
},
{
"name": "sourceType",
"type": "string"
},
{
"name": "sourceUser",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm fscache rescan ==

force fscache rescan

parameters:

<nowiki>
{
"command": "fscacheRescan",
"parameters": [
{
"name": "path",
"type": "string"
},
{
"name": "maxAge",
"type": "integer"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm metacache ==
=== doveadm metacache clean ===

clean metacache content for given user or all users

parameters:

<nowiki>
{

"command": "metacacheClean",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "days",
"type": "integer"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache flush ===

flush metacache contents to storage for given user or all users

parameters:

<nowiki>
{
"command": "metacacheFlush",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache unpack ===

unpack metacache index bundle to target directory

parameters:

<nowiki>
{
"command": "metacacheUnpack",
"parameters": [
{
"name": "bundleName",
"type": "string"
},
{
"name": "bundle",
"type": "string"
},
{
"name": "destinationDirectory",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache flushall ===

flush metacache to storage for all users

parameters:

<nowiki>
{
"command": "metacacheFlushall",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache remove ===

remove metacache for given mask

parameters:

<nowiki>
{
"command": "metacacheRemove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "mask",
"type": "string"
}
]
}
</nowiki>
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache list ===

list local metacache contents

parameters:

<nowiki>
{
"command": "metacacheList",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm obox user delete ==

delete user data from storage, Cassandra and local caches (metacache and fscache).

parameters:

<nowiki>
{
"command": "oboxUserDelete",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

example:

<nowiki>
[
[
"oboxUserDelete",
{
"allUsers": 0,
"socketPath": "",
"user": "testuser003",
"userFile": ""
},
"aa"
]
]

# curl -v -u doveadm:hellodoveadm -X POST http://localhost:ype: application/json" -d '[["oboxUserDelete", {"allUsers":0,"user":"testuser003"}, "aa"]]'
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"aa"
]
]

CLI: doveadm obox user delete –u testuser003
</nowiki>

== doveadm sieve ==

Commands related to handling Sieve scripts.

=== doveadm sieve list ===

list user sieve scripts

parameters:

<nowiki>
{
"command": "sieveList",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve get ===

get user sieve script

parameters:

<nowiki>
{
"command": "sieveGet",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "scriptname",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve put ===

inject sieve script to user

parameters:

<nowiki>
{
"command": "sievePut",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "activate",
"type": "boolean"
},
{
"name": "scriptname",
"type": "string"
},
{
"name": "file",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve delete ===

delete user sieve

parameters:

<nowiki>
{
"command": "sieveDelete",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "ignoreActive",
"type": "boolean"
},
{
"name": "scriptname",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve activate ===

activate user sieve script

parameters:

<nowiki>
{
"command": "sieveActivate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "scriptname",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve deactivate ===

deactivate user sieve

parameters:

<nowiki>
{
"command": "sieveDeactivate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve rename ===

rename user sieve script

parameters:

<nowiki>
{
"command": "sieveRename",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "oldname",
"type": "string"
},
{
"name": "newname",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm fts ==
Dovecot fts indexing commands.

=== doveadm fts lookup ===

query user fts indexed data

parameters:

<nowiki>
{
"command": "ftsLookup",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts expand ===

<nowiki>
{
"command": "ftsExpand",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts tokenize ===

<nowiki>
{
"command": "ftsTokenize",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "language",
"type": "string"
},
{
"name": "text",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts optimize ===

<nowiki>
{
"command": "ftsOptimize",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts rescan ===

<nowiki>
{
"command": "ftsRescan",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

Template:DoveadmHTTPapi

2017-03-15T12:04:14Z

Oskarikentta: /* doveadm director ring remove */

== Table of Contents ==
__TOC__

== 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:

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

=== 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:

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

Basic auth usage:
<nowiki>
curl -H "Authorization: Basic <base64 doveadm:doveadm_password>"
http://host:port/doveadm/v1
</nowiki>
or by letting curl to form the base64 encoded authentication basig authentication header:

<nowiki>
curl –u doveadm:password http://host:port/doveadm/v1
</nowiki>

=== 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:

<nowiki>

[
[
"command1",
{
"parameter1": "value",
"parameter2": "value",
"parameter3": "value"
},
"identifier"
]
]
</nowiki>
Multiple commands can be submitted in one json payload:
<nowiki>
[
[
"command1",
{
"parameter1": "value",
"parameter2": "value"
},
"identifier1"
],
[
"command2",
{
"parameter1": "value",
"parameter2": "value"
},
"identifier2"
]
]
</nowiki>

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:

<nowiki>

son payload:

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

</nowiki>

submitting the command with curl:

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

command line equivalent

doveadm reload

=== successful response ===

<nowiki>

[
[
"doveadmResponse",
[],
"a2"
]
]
</nowiki>

=== failure response ===

<nowiki>

[
[
"error",
{
"exitCode": 68,
"type": "exitCode"
},
"a2"
]
</nowiki>

=== failure codes ===

{| class="wikitable"
|-
|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
|}

== Supported commands ==

== doveadm service ==
=== doveadm service stop ===

stop one or more dovecot services on target host

<nowiki>
{
"command": "serviceStop",
"parameters": [
{
"name": "service",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|service
|string array
|Name of service to stop
|[“imap”,”imap-hibernate”]
|}

example:

<nowiki>
[
[
"serviceStop",
{
"service": [
"imap",
"imap-hibernate"
]
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["serviceStop",{"service":["imap","imap-hibernate"]},"aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm service stop imap imap-hibernate
</nowiki>

=== doveadm stop ===

stop dovecot on the target host
<nowiki>

{
"command": "stop",
"parameters": []
}

no parameters
</nowiki>
example:
<nowiki>
[
[
"stop",
{},
"a1"
]
]

# curl -u doveadm:hellodoveadm -X POST http://localhost:8080/doveadm/v1 -H "Content-Type: application/json" -d '[["stop",{},"a1"]]'

CLI: doveadm stop
</nowiki>

=== doveadm reload ===

reload dovecot configuration

<nowiki>
{
"command": "reload",
"parameters": []
}
</nowiki>

example:

<nowiki>
[
[
"reload",
{},
"a2"
]
]

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

CLI: doveadm reload
</nowiki>

== doveadm stats ==
=== doveadm stats dump ===

dump collected dovecot statistics

<nowiki>
{
"command": "statsDump",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "type",
"type": "string"
},
{
"name": "filter",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|+parameters
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|type
|String
|Type of stats to dump
|global
|-
|filter
|String
|Dump filter
|last_update 1483101542
|}

Example:

<nowiki>
[
[
"statsDump",
{
"type": "global"
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["statsDump",{"type":"global"},"aa"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"auth_cache_hits": "0",
"auth_cache_misses": "0",
"auth_db_tempfails": "0",
"auth_failures": "0",
"auth_master_successes": "0",
"auth_successes": "0",
"clock_time": "0.0",
"disk_input": "0",
"disk_output": "0",
"fscache_read": "0",
"fscache_stat": "0",
"fscache_write": "0",
"idx_del": "0",
"idx_iter": "0",
"idx_read": "0",
"idx_read_usecs": "0",
"idx_wbytes": "0",
"idx_write": "0",
"idx_write_usecs": "0",
"invol_cs": "0",
"last_update": "0.000000",
"mail_cache_hits": "0",
"mail_lookup_attr": "0",
"mail_lookup_path": "0",
"mail_read_bytes": "0",
"mail_read_count": "0",
"maj_faults": "0",
"min_faults": "0",
"num_cmds": "0",
"num_connected_sessions": "0",
"num_logins": "0",
"obox_copy": "0",
"obox_del": "0",
"obox_iter": "0",
"obox_read": "0",
"obox_read_usecs": "0",
"obox_stat": "0",
"obox_wbytes": "0",
"obox_write": "0",
"obox_write_usecs": "0",
"read_bytes": "0",
"read_count": "0",
"reset_timestamp": "1483104199",
"sys_cpu": "0.0",
"user_cpu": "0.0",
"vol_cs": "0",
"write_bytes": "0",
"write_count": "0"
}
],
"aa"
]
]

CLI: doveadm stats dump global
</nowiki>

=== doveadm stats reset ===
reset dovecot statistics counters
<nowiki>

{
"command": "statsReset",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|}

example:

<nowiki>
[
[
"statsReset",
{},
"aa"
]
]

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

CLI: doveadm stats reset
</nowiki>

== doveadm penalty ==

<nowiki>
show current penalties

{
"command": "penalty",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "netmask",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|string
|Path to doveadm socket
|/var/run/dovecot-server
|-
|netmask
|string
|To reduce/filter the output supply an IP address or a network range in CIDR notation (ip/mask)
|10.0.0.0/24
|}

example:

<nowiki>
[
[
"penalty",
{},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["penalty",{},"aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm penalty
</nowiki>

== doveadm kick ==

Kick user from dovecot. Applicable to session in dovecot backend only

<nowiki>
{
"command": "kick",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "force",
"type": "boolean"
},
{
"name": "mask",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|force
|Boolean
|Do a forced kick?
|0
|-
|mask
|String
|Uid mask
|testuser001
|}

example:

<nowiki>
[
[
"kick",
{
"force": 0,
"mask": "testuser001"
},
"aa"
]
]

# curl -v -u doveadm:hellodoveadm –H “Content-Type: application/json" -d '[["kick", {"mask":"testuser001"}, "aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm kick testuser001
</nowiki>

response for succesfull kick:

<nowiki>
[
[
"doveadmResponse",
[
{
"result": "testuser001"
}
],
"aa"
]
]
</nowiki>

response in case kick failed:

<nowiki>
[
[
"error",
{
"exitCode": 68,
"type": "exitCode"
},
"aa"
]
]
</nowiki>

== doveadm who ==

<nowiki>
list active dovecot sessions

{
"command": "who",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "separateConnections",
"type": "boolean"
},
{
"name": "mask",
"type": "array"
}
]
}
</nowiki>

parameters

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|string
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|separateConnections
|Boolean
|Show each user connection in separate entries
|0
|-
|mask
|string array
|Uid mask
|testuser001
|}

Example:

<nowiki>
[
[
"who",
{
"mask": "",
"separateConnections": 0,
"socketPath": ""
},
"aa"
]
]

# curl -v -u doveadm:hellodoveadm -X POST http://localhost:ype: application/json" -d '[["who", {}, "aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm who
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"connections": "1",
"ips": "(127.0.0.1)",
"pids": "(4999)",
"service": "imap",
"username": "testuser001"
}
],
"aa"
]
]
</nowiki>

== doveadm director ==
=== doveadm director status ===

Show backend statuses on directors. Available only in directors

<nowiki>
[
{
"command": "directorStatus",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "tag",
"type": "string"
}
]
}
]
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|String
|Show director status for Tagged hosts only
|NewBackend
|}

example:

<nowiki>
[
[
"directorStatus",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorStatus",{},"bb"]]' http://localhost:8080/doveadm/v1

</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"mail server ip": "10.0.0.234",
"state": "up",
"state-changed": "2016-12-15 08:31:37",
"tag": "",
"users": "1",
"vhosts": "100"
},
{
"mail server ip": "10.0.0.235",
"state": "up",
"state-changed": "2016-12-15 08:31:04",
"tag": "",
"users": "0",
"vhosts": "100"
}
],
"bb"
]
]

CLI: doveadm director status
</nowiki>

=== doveadm director map ===

list current user → host mappings. Applicable to director only

<nowiki>

"command": "directorMap",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "usersFile",
"type": "string"
},
{
"name": "hashMap",
"type": "boolean"
},
{
"name": "userMap",
"type": "boolean"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

parameters

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|usersFile
|String
|provide Path to users list. One username per line
|/etc/dovecot/userlist.txt
|-
|hashMap
|Boolean
|Output users as hashmap
|True
|-
|userMap
|Boolean
|Output users as userlist
|True
|-
|host
|String
|Show only mappings to given host
|10.0.0.234
|}

example:

<nowiki>
[
[
"directorMap",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorMap",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"expire time": "2016-12-30 14:52:56",
"hash": "3853430566",
"mail server ip": "10.0.0.235",
"user": "samik"
}
],
"bb"
]
]

CLI: doveadm director map
</nowiki>

=== doveadm director add ===

add backend to director ring

<nowiki>
{
"command": "directorAdd",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "tag",
"type": "string"
},
{
"name": "host",
"type": "string"
},
{
"name": "vhostCount",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|tag
|String
|apply tag to backend
|/etc/dovecot/userlist.txt
|-
|host
|String
|backend ip to add
|10.0.0.234
|-
|vhostCount
|String
|vhost count to add
|100
|}

Example:

<nowiki>
[
[
"directorAdd",
{
"host": "10.0.234"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorAdd",{"host":"10.0.234"},"bb"]]' http://localhost:8080/doveadm/v1

CLI: doveadm director add 10.0.0.234
</nowiki>

=== doveadm director update ===

<nowiki>
{
"command": "directorUpdate",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
},
{
"name": "vhostCount",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|string
|Show director status for tagged hosts only
|NewBackend
|}

=== doveadm director up ===

<nowiki>
{
"command": "directorUp",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|string
|Show director status for tagged hosts only
|NewBackend
|}

=== doveadm director down ===

<nowiki>
{
"command": "directorDown",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|string
|Show director status for tagged hosts only
|NewBackend
|}

=== doveadm director remove ===

remove backend from director ring

<nowiki>
{
"command": "directorRemove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|host
|String
|backend to remove
|10.0.0.134
|}

example:

<nowiki>
[
[
"directorRemove",
{
"host": "10.0.0.234"
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRemove",{"host":"10.0.0.234"},"aa"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"aa"
]
]

CLI: doveadm director remove 10.0.0.234
</nowiki>

=== doveadm director move ===

move user mapping from backend to another or create director mapping for an user
<nowiki>
{
"command": "directorMove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|user
|String
|User uid to move
|testuser001
|-
|host
|string
|Target backend ip as listed in doveadm doveadm director status
|10.0.0.234
|}

example:

<nowiki>
[
[
"directorMove",
{
"host": "10.0.234",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorMove",{"user":"samik","host":"10.0.234"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director move samik 10.0.0.234
</nowiki>

== doveadm director kick ==

<nowiki>
{
"command": "directorKick",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|user
|String
|uid of user to kick
|samik
|}

example:

<nowiki>
[
[
"directorKick",
{
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorKick",{"user":"samik"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director kick samik
</nowiki>

=== doveadm director flush ===

flush connection mappings to one backend at director level. All users mapped to given host will be flushed from the hashmap table and will be redistributed to backends.

Parameters:

<nowiki>
{
"command": "directorFlush",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "forceFlush",
"type": "boolean"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|forceFlush
|Boolean
|Flag to make flush forced
|True
|-
|host
|String
|Backend ip address from doveadm director status list
|10.0.0.234
|}

example:

<nowiki>
[
[
"directorFlush",
{
"host": "10.0.0.234"
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorFlush",{"host":"10.0.0.234"},"aa"]]' http://localhost:8080/doveadm/v1

</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"aa"
]
]
CLI: doveadm director flush 10.0.234
</nowiki>

=== doveadm director dump ===

Dumb the current director backend host configuration as commands

<nowiki>
{
"command": "directorDump",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|}

example:

<nowiki>
[
[
"directorDump",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorDump",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"command": "add",
"host": "10.0.0.234",
"socket-path": "/var/run/dovecot/director-admin",
"vhost_count": "100"
},
{
"command": "add",
"host": "10.0.0.235",
"socket-path": "/var/run/dovecot/director-admin",
"vhost_count": "100"
}
],
"bb"
]
]

CLI: doveadm director dump
</nowiki>

=== doveadm director ring add ===

add new director to director ring

parameters:

<nowiki>
{
"command": "directorRingAdd",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "ip",
"type": "string"
},
{
"name": "port",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|ip
|String
|director ip address to add
|10.0.0.233
|-
|port
|String
|port number to use if not default
|9143
|}

example:

<nowiki>
[
[
"directorRingAdd",
{
"ip": "10.0.0.233"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRingAdd",{"ip":"10.0.0.233"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director ring add 10.0.0.233
</nowiki>

=== doveadm director ring remove ===

remove director from director ring

parameters:

<nowiki>
{
"command": "directorRingRemove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "ip",
"type": "string"
},
{
"name": "port",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|}

example:

<nowiki>
[
[
"directorRingRemove",
{
"ip": "10.0.0.233"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRingRemove",{"ip":"10.0.0.233"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director ring remove 10.0.0.233
</nowiki>

=== doveadm director ring status ===

show director ring status

parameters:

<nowiki>

{
"command": "directorRingStatus",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|}

example:

<nowiki>
[
[
"directorRingStatus",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRingStatus",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>

[
"doveadmResponse",
[
{
"director ip": "10.0.0.232",
"last failed": "never",
"port": "9143",
"status": "synced",
"type": "self"
},
{
"director ip": "10.0.0.233",
"last failed": "never",
"port": "9143",
"status": "",
"type": ""
}
],
"bb"
]
]

CLI: doveadm director ring status
</nowiki>

== doveadm proxy ==

The doveadm proxy commands are used to list or kick active Dovecot proxy connections.

=== doveadm proxy list ===

list active connections in the dovecot proxy

parameters:

<nowiki>
{
"command": "proxyList",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|}

example:

<nowiki>
[
[
"proxyList",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["proxyList",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"dest-ip": "127.0.0.1",
"dest-port": "1143",
"service": "imap",
"src-ip": "10.0.0.153",
"username": "samik"
}
],
"bb"
]
]

CLI: doveadm proxy list
</nowiki>

=== doveadm proxy kick ===

kick user session from proxy. applicable to imap/pop3/managesieve sessions

parameters:

<nowiki>
{
"command": "proxyKick",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|userid to kick
|samik
|}

example:

<nowiki>
[
[
"proxyKick",
{
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["proxyKick",{"user":"samik"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"count": "1"
}
],
"bb"
]
]

CLI: doveadm proxy kick samik
</nowiki>

== doveadm logs errors ==

fetch errors log

paraments:

<nowiki>
{
"command": "logErrors",
"parameters": [
{
"name": "since",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|}

example:

<nowiki>
[
[
"logErrors",
{},
"a2"
]
]

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

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"prefix": "stats",
"text": "Stats client input error: Invalid level",
"timestamp": "Dec 09 16:24:00",
"type": "Error"
},
{
"prefix": "doveadm(127.0.0.1)",
"text": "read(/var/run/dovecot/stats) unexpectedly disconnected",
"timestamp": "Dec 09 16:24:00",
"type": "Fatal"
},
{
"prefix": "stats",
"text": "Stats client input error: Invalid level",
"timestamp": "Dec 09 16:24:22",
"type": "Error"
},
{
"prefix": "stats",
"text": "Stats client input error: Invalid level",
"timestamp": "Dec 09 16:27:48",
"type": "Error"
},
{
"prefix": "director",
"text": "Empty server list",
"timestamp": "Dec 09 16:29:13",
"type": "Error"
},
{
"prefix": "director",
"text": "Invalid value for director_mail_servers setting",
"timestamp": "Dec 09 16:29:13",
"type": "Fatal"
}
],
"a2"
]
]

CLI: doveadm log errors
</nowiki>

== doveadm dict ==
=== doveadm dict get ===

get user key value from configured dictionary

parameters:

<nowiki>
{
"command": "dictGet",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to query
|samik
|-
|dictUri
|String
|optional URI for dictionary to query
|
|-
|key
|String
|key to query
|
|}

=== doveadm dict set ===

set user key value in configured dictionary

parameters:

<nowiki>
{
"command": "dictSet",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
},
{
"name": "value",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|samik
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|key
|String
|dictionary key to modify
|
|-
|value
|string
|value to set
|
|}

=== doveadm dict unset ===

unset user key value in configured dictionary

parameters:

<nowiki>
{
"command": "dictUnset",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|key
|String
|dictionary key to unset
|
|}
== doveadm dict inc ==

increase users key value in dictionary

parameters:

<nowiki>
{
"command": "dictInc",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
},
{
"name": "difference",
"type": "integer"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|optional URI for dictionary to modify
|
|-
|key
|String
|dictionary key to increase
|
|-
|difference
|integer
|increment value
|
|}

=== doveadm dict iter ===

list user keys in dictionary

parameters:

<nowiki>
{
"command": "dictIter",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "exact",
"type": "boolean"
},
{
"name": "recurse",
"type": "boolean"
},
{
"name": "noValue",
"type": "boolean"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "prefix",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|exact
|Boolean
|list only exact matches
|
|-
|recurce
|Boolean
|do recursive search
|
|-
|noValue
|Boolean
|list also keys that have no value set
|
|-
|prefix
|String
|search only keys with given prefix
|
|}

== doveadm fs ==
=== doveadm fs get ===

get object from storage

parameters:

<nowiki>
{
"command": "fsGet",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem to fetch
|
|}

=== doveadm fs put ===

put object to storage

parameters:

<nowiki>
{
"command": "fsPut",
"parameters": [
{
"name": "hash",
"type": "string"
},
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "inputPath",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|hash
|string
|
|
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|inputPath
|String
|source object path in local filesystem
|
|-
|path
|String
|object path filesystem to put
|
|}

=== doveadm fs copy ===

copy object in storage

parameters:

<nowiki>
{
"command": "fsCopy",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "sourcePath",
"type": "string"
},
{
"name": "destinationPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|sourcePathh
|String
|source object path
|
|-
|Destination path
|String
|destination object path in filesystem
|
|}

=== doveadm fs stat ===

fetch fs driver statistics

parameters:

<nowiki>
{
"command": "fsStat",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem fetch statistics for
|
|}

=== doveadm fs metadata ===

get filesystem object metadata

parameters:

<nowiki>
{
"command": "fsMetadata",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem fetch statistics for
|
|}

=== doveadm fs delete ===

delete object from storage

<nowiki>
{
"command": "fsDelete",
"parameters": [
{
"name": "recursive",
"type": "boolean"
},
{
"name": "maxParallel",
"type": "integer"
},
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem fetch statistics for
|
|-
|recursive
|Boolean
|do a recursive delete of path
|
|-
|maxParallel
|integer
|max number of parallel workers
|
|}

=== doveadm fs iter ===

list objects in given fs path

parameters:

<nowiki>
{
"command": "fsIter",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|path in filesystem to list
|
|}

=== doveadm fs iter-dirs ===
ist subfolders in given path

parameters:

<nowiki>
{
"command": "fsIterDirs",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|path in filesystem to list for subfolders
|
|}

== doveadm auth cache flush ==

flush authentication cache for one user or all users

parameters:

<nowiki>
{
"command": "authCacheFlush",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String array
|optional list of users in flush
|[“samik”,”samitest”]
|}

example:

<nowiki>
[
[
"authCacheFlush",
{
"user": [
"samik"
]
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["authCacheFlush",{"user":["samik"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"entries": "0"
}
],
"bb"
]
]

CLI: doveadm auth cache flush samik
</nowiki>

== doveadm user ==

do a userdb lookup for an user

<nowiki>
{
"command": "user",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "authInfo",
"type": "array"
},
{
"name": "field",
"type": "string"
},
{
"name": "expandField",
"type": "string"
},
{
"name": "userdbOnly",
"type": "boolean"
},
{
"name": "userMask",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|authInfo
|String array
|auth_info specifies additional conditions for the user command. The auth_info option string has to be given as name=value pair. For multiple conditions the -x option could be supplied multiple times.
Possible names for the auth_info are:
service
The service for which the userdb lookup should be tested. The value may be the name of a service, commonly used with Dovecot. For example: imap, pop3 or smtp.
lip
The local IP address (server) for the test.
rip
The remote IP address (client) for the test.
lport
The local port, e.g. 143
rport
The remote port, e.g. 24567
|sevice=imap
|-
|field
|String
|fetch only one specified field instead of all
|
|-
|expandField
|String
|expand configuration variable with user specific values
|
|-
|userdbOnly
|Boolean
|only fetch from userdb lookup and don’t process passdb
|
|-
|userMask
|String array
|search filter
|
|}

example:

<nowiki>
[
[
"user",
{
"userMask": [
"samik"
]
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["user",{"userMask":["samik"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
{
"samik": {
"gid": "1000",
"home": "/var/vmail/samik",
"junkflag": "0",
"mail": "Maildir:/mails/mails/samik/Maildir",
"namespace/Junk/hidden": "no",
"namespace/Junk/list": "yes",
"uid": "1000"
}
},
"bb"
]
]

CLI: doveadm user samik
</nowiki>

== doveadm mailbox ==
=== doveadm mailbox metadata set ===

set user mailbox metadata

parameters:

<nowiki>
{
"command": "mailboxMetadataSet",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "key",
"type": "string"
},
{
"name": "value",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata set
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to set
|
|-
|value
|String
|metadata value to set
|
|}

example:

<nowiki>
[
[
"mailboxMetadataSet",
{
"key": "/private/comment",
"mailbox": "INBOX",
"user": "samik",
"value": "test"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataSet",{"user":"samik","mailbox":"INBOX","key":"/private/comment","value":"test"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox metadata set –u samik INBOX /private/comment test
</nowiki>

=== doveadm mailbox metadata unset ===

unset user mailbox metadata

parameters:

<nowiki>
{
"command": "mailboxMetadataUnset",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata unset
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to unset
|
|}

example:

<nowiki>
[
[
"mailboxMetadataUnset",
{
"key": "/private/comment",
"mailbox": "INBOX",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataUnset",{"user":"samik","mailbox":"INBOX","key":"/private/comment"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox metadata unset –u samik INBOX /private/comment
</nowiki>

=== doveadm mailbox metadata get ===

get user mailbox metadata

parameters:

<nowiki>
{
"command": "mailboxMetadataGet",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata get
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to get
|
|}

example:

<nowiki>
[
[
"mailboxMetadataGet",
{
"key": "/private/comment",
"mailbox": "INBOX",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataGet",{"user":"samik","mailbox":"INBOX","key":"/private/comment"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response

<nowiki>
[
[
"doveadmResponse",
[
{
"value": "plaa"
}
],
"bb"
]
]

CLI: doveadm mailbox metadata get –u samik INBOX /private/comment
</nowiki>

=== doveadm mailbox list ===

list user mailbox metadata for a folder

parameters:

<nowiki>

"command": "mailboxMetadataList",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "keyPrefix",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata get
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to get
|
|-
|keyPrefix
|String
|search prefix for keys
|
|-
|mailbox
|String
|mailbox to fetch metadata from
|
|}

example:

<nowiki>
[
[
"mailboxMetadataList",
{
"mailbox": "INBOX",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataList",{"user":"samik","mailbox":"INBOX"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"key": "comment"
},
{
"key": "specialuse"
}
],
"bb"
]
]

CLI: doveadm mailbox metadata list –u samik INBOX
</nowiki>

=== doveadm mailbox status ===

fetch user mailbox status

parameters:

<nowiki>
{
"command": "mailboxStatus",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "totalSum",
"type": "boolean"
},
{
"name": "field",
"type": "array"
},
{
"name": "mailboxMask",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply status fetch
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|totalSum
|boolean
|
|
|-
|field
|String array
|fields to fetch
|all
|-
|mailboxMask
|String array
|fetch status on given mailboxes
|
|}

example:

<nowiki>

[
[
"mailboxStatus",
{
"field": [
"all"
],
"mailboxMask": [
"INBOX",
"INBOX/*",
"*"
],
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxStatus",{"user":"samik","field":["all"],"mailboxMask":["INBOX","INBOX/*","*"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"guid": "21b588150b156558eb3500007afd792c",
"highestmodseq": "5",
"mailbox": "Junk",
"messages": "0",
"recent": "0",
"uidnext": "1",
"uidvalidity": "1483019529",
"unseen": "0",
"vsize": "0"
},
{
"guid": "21b588150b156558eb3500007afd792c",
"highestmodseq": "5",
"mailbox": "INBOX",
"messages": "0",
"recent": "0",
"uidnext": "1",
"uidvalidity": "1483019529",
"unseen": "0",
"vsize": "0"
}
],
"bb"
]
]

CLI: doveadm mailbox status –u samik all “*”
</nowiki>

=== doveadm mailbox list ===

fetch user folder list

parameters:

<nowiki>
{
"command": "mailboxList",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mutf7",
"type": "boolean"
},
{
"name": "utf8",
"type": "boolean"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "mailboxMask",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid to apply mailbox list
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|mutf7
|Boolean
|
|
|-
|utf8
|Boolean
|fetch only certain fields instead of all
|
|-
|subscription
|Boolean
|
|
|-
|mailboxMask
|String array
|fetch list of given mailboxes
|
|}

example:

<nowiki>
[
[
"mailboxList",
{
"user": "samik"
},
"bb"
]
]
# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxList",{"user":"samik"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"mailbox": "Junk"
},
{
"mailbox": "INBOX"
}
],
"bb"
]
]

CLI: doveadm mailbox list –u samik
</nowiki>

=== doveadm mailbox create ===
create mailbox folder for user

parameters:

<nowiki>
{
"command": "mailboxCreate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "guid",
"type": "string"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply mailbox create
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|subscription
|Boolean
|
|
|-
|mailbox
|String array
|list of mailbox folders to create
|
|}

example:

<nowiki>
[
[
"mailboxCreate",
{
"mailbox": [
"INBOX/myfolder"
],
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxCreate",{"user":"samik","mailbox":["INBOX/myfolder"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>

[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox create –u samik INBOX/myfolder
</nowiki>

=== doveadm mailbox delete ===

delete user mailbox folder

parameters:

<nowiki>
{
"command": "mailboxDelete",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "requireEmpty",
"type": "boolean"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "recursive",
"type": "boolean"
},
{
"name": "unsafe",
"type": "boolean"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply delete
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|requireEmpty
|Boolean
|only delete if folder is empty
|
|-
|subscription
|Boolean
|
|
|-
|recursive
|Boolean
|delete also subfolders
|
|-
|unsafe
|Boolean
|
|
|-
|mailbox
|String array
|list of mailbox folders to create
|
|}

example:

<nowiki>
[
[
"mailboxDelete",
{
"mailbox": [
"INBOX/myfolder"
],
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxDelete",{"user":"samik","mailbox":["INBOX/myfolder"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox delete –u samik INBOX/myfolder
</nowiki>

=== doveadm mailbox rename ===

rename user folder

parameters:

<nowiki>
{
"command": "mailboxRename",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "newName",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply mailbox rename
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|subscriptions
|Boolean
|
|
|-
|newName
|String
|mailbox new name
|
|-
|mailbox
|String
|mailbox to rename
|
|}

example:

<nowiki>
[
[
"mailboxRename",
{
"mailbox": "INBOX/myfolder",
"newName": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxRename",{"user":"samik","mailbox":"INBOX/myfolder","newName":"INBOX/myfoldertoo"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox rename –u samik INBOX/myfolder INBOX/myfoldertoo
</nowiki>

=== doveadm mailbox subscribe ===

subscribe user to a mailbox

parameters:

<nowiki>
{
"command": "mailboxSubscribe",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply subscribe
|
|-
|userFile
|String
|optionally fetch usernames from. One username per line
|
|-
|mailbox
|String
|mailbox to subscribe
|
|}

example:

<nowiki>
[
[
"mailboxSubscribe",
{
"mailbox": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxSubscribe",{"user":"samik","mailbox":"INBOX/myfoldertoo"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:
<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox subscribe –u samik INBOX/myfoldertoo
</nowiki>

=== doveadm mailbox unsubscribe ===

unsubscribe user from an folder

parameters:

<nowiki>
{
"command": "mailboxUnsubscribe",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply unsubscribe
|
|-
|userFile
|String
|optionally fetch usernames from. One username per line
|
|-
|mailbox
|String
|mailbox to unsubscribe
|
|}

example:

<nowiki>
[
[
"mailboxUnsubscribe",
{
"mailbox": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxUnsubscribe",{"user":"samik","mailbox":"INBOX/myfoldertoo"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox unsubscribe –u samik INBOX/myfoldertoo
</nowiki>

=== doveadm mailbox update ===

update user mailbox information

parameters:

<nowiki>
{
"command": "mailboxUpdate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailboxGuid",
"type": "string"
},
{
"name": "uidValidity",
"type": "string"
},
{
"name": "minNextUid",
"type": "string"
},
{
"name": "minFirstRecentUid",
"type": "string"
},
{
"name": "minHighestModseq",
"type": "string"
},
{
"name": "minHighestPvtModseq",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply update
|
|-
|userFile
|String
|optionally fetch usernames from. One username per line
|
|-
|mailbox
|String
|mailbox to unsubscribe
|
|-
|mailboxGuid
|String
|set mailbox guid
|
|-
|uidValidity
|String
|set mailbox uidvalidity
|
|-
|minNextuid
|String
|set mailbox minimum next uid
|
|-
|minFirstRecentuid
|String
|set mailbox minimum recent uid
|
|-
|minHighestModseq
|String
|
|
|-
|minHighestPvtModseq
|String
|
|
|}

=== doveadm mailbox save ===

save mail into users mailbox

parameters:

<nowiki>
{
"command": "save",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "file",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to save mail into
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|mailbox
|String
|mailbox to unsubscribe
|
|-
|file
|String
|mail to inject
|
|}

example:

<nowiki>
[
[
"save",
{
"file": "From: Joulu Pukki <joulu.pukki@korvatunturi.fi>\nSubject: plaa\n\nmail body\n",
"mailbox": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["save",{"user":"samik","mailbox":"INBOX/myfoldertoo","file":"From: Joulu Pukki <joulu.pukki@korvatunturi.fi>\nSubject: plaa\n\nmail body\n"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]
</nowiki>

== doveadm fetch ==

fetch data from user mailbox

parameters:

<nowiki>
{
"command": "fetch",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "field",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to fetch data
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|field
|String array
|fields to fetch. Supported fields as of dovecot 2.2.26: hdr.<name> body.<section> binary.<section> user mailbox mailbox-guid seq uid guid flags modseq hdr body body.snippet text text.utf8 size.physical size.virtual date.received date.sent date.saved date.received.unixtime date.sent.unixtime date.saved.unixtime imap.envelope imap.body imap.bodystructure pop3.uidl pop3.order refcount storageid
|
|-
|query
|String array
|search query to user
|
|}

example:

<nowiki>
[
[
"fetch",
{
"field": [
"text"
],
"query": [
"mailbox",
"INBOX/myfoldertoo"
],
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["fetch",{"user":"samik","field":["text"],"query":["mailbox","INBOX/myfoldertoo"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"text": "From: Joulu Pukki <joulu.pukki@korvatunturi.fi>\nSubject: plaa\n\nmail body\n"
}
],
"bb"
]
]

CLI: doveadm fetch –u samik “text” mailbox INBOX/myfoldertoo
</nowiki>

== doveadm index ==

index user mailbox folder or folders

parameters:

<nowiki>
{
"command": "index",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "queue",
"type": "boolean"
},
{
"name": "maxRecent",
"type": "string"
},
{
"name": "mailboxMask",
"type": "string"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to index
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|query
|Boolean
|max number of recent mails to index
|
|-
|maxRecent
|String
|max number of recent mails to index
|
|-
|mailboxMask
|String
|mailbox search mask to apply indexing into
|
|}

example:

<nowiki>
[
[
"index",
{
"mailboxMask": "INBOX*",
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["index",{"user":"samik","mailboxMask":"INBOX*"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm index –u samik “INBOX*”
</nowiki>

== doveadm altmove ==

move mails between primary and alternative mailbox storage locations. Applicable to mdbox and sdbox mailbox formats only

parameters:

<nowiki>
{
"command": "altmove",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "reverse",
"type": "boolean"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to apply move
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|reverse
|Boolean
|search query to apply to mail move
|
|-
|query
|String array
|search query to apply to mail move
|
|}

example:

<nowiki>
[
[
"altmove",
{
"query": [
"mailbox",
"INBOX/myfoldertoo",
"savedbefore",
"since",
"30d"
],
"reverse": 0,
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["altmove",{"user":"samik","reverse":0,"query":["mailbox","INBOX/myfoldertoo","savedbefore","since","30d"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

== doveadm deduplicate ==

This command is used to expunge duplicated messages in mailboxes

parameters:

<nowiki>
{
"command": "deduplicate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "byMsgid",
"type": "boolean"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to deduplicate
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|byMsgId
|Boolean
|deduplicate by Message-ID instead of guid
|
|-
|query
|String array
|search query to apply to deduplicate
|
|}

== doveadm expunge ==

Expunge messages matching given search query

parameters:

<nowiki>
{
"command": "expunge",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "deleteEmptyMailbox",
"type": "boolean"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to expunge
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|deleteEmptyMailbox
|Boolean
|delete also mailbox if it’s empty after expunge has been applied
|
|-
|query
|String array
|search query to apply to expunge
|
|}

== doveadm flags ==
add, remove or replace messages' flags

=== doveadm flags add ===

add flag to a message or messages

parameters:

<nowiki>
{
"command": "flagsAdd",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "flag",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to add flags
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|flag
|String array
|list of flags to add
|
|-
|query
|String array
|search query to apply to flag add
|
|}

=== doveadm flags remove ===

remove flags from message or messages

parameters:

<nowiki>
{
"command": "flagsRemove",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "flag",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to add flags
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|flag
|String array
|list of flags to remove
|
|-
|query
|String array
|search query to apply to flag remove
|
|}

=== doveadm flags replace ===

Replace flags with another flag in message or messages. Replaces all current flags with the ones in the parameter list

parameters:

<nowiki>
{
"command": "flagsReplace",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "flag",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to replace flags
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|flag
|String array
|list of flags to replace with
|
|-
|query
|String array
|search query to apply to flag replace
|
|}

== doveadm import ==

Import messages matching given search query

parameters:

<nowiki>
{
"command": "import",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "subscribe",
"type": "boolean"
},
{
"name": "sourceLocation",
"type": "string"
},
{
"name": "destParentMailbox",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to apply import
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|subscribe
|boolean
|when enabled possible newly created folders are also subscibed
|
|-
|sourceLocation
|String
|location of source mailboxes
|
|-
|destParentMailbox
|String
|destination parent mailbox where to import
|
|-
|query
|String array
|search query for messages to import
|
|}

== doveadm force-resync ==

Under certain circumstances it may happen, that dovecot is unable to automatically solve problems with mailboxes. In such situations the force-resync command may be helpful. It tries to fix all problems. For sdbox and mdbox mailboxes the storage files will be also checked.

parameters:

<nowiki>
{
"command": "forceResync",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailboxMask",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|user
|String
|uid of user to apply resync
|
|-
|mailboxMask
|String
|apply forced resync on given mailboxes
|INBOX*
|}

example:

<nowiki>
[
[
"forceResync",
{
"mailboxMask": "INBOX*",
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["forceResync",{"user":"samik","mailboxMask":"INBOX*"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm force-resync –u samik “INBOX*”
</nowiki>

== doveadm purge ==

Remove messages with refcount=0 from mdbox files

parameters:

<nowiki>
{
"command": "purge",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to apply purge
|
|}

== doveadm search ==

Show a list of mailbox GUIDs and message UIDs matching given search query

parameters:

<nowiki>
{
"command": "search",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|user
|String
|uid of user to apply purge
|
|-
|query
|String array
|search query
|
|}

example:

<nowiki>
[
[
"search",
{
"query": [
"mailbox",
"INBOX*",
"all"
],
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["search",{"user":"samik","query":["mailbox","INBOX*","all"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"mailbox-guid": "cf497f128caf7c58612200007afd792c",
"uid": "1"
}
],
"bb"
]
]

CLI: doveadm search –u samik mailbox “INBOX*” all
</nowiki>

== doveadm copy ==

Copy messages matching the given search query into another mailbox

parameters:

<nowiki>
{
"command": "copy",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "destinationMailbox",
"type": "string"
},
{
"name": "sourceType",
"type": "string"
},
{
"name": "sourceUser",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm move ==

Move messages matching the given search query into another mailbox

parameters:

<nowiki>
{
"command": "move",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "destinationMailbox",
"type": "string"
},
{
"name": "sourceType",
"type": "string"
},
{
"name": "sourceUser",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm fscache rescan ==

force fscache rescan

parameters:

<nowiki>
{
"command": "fscacheRescan",
"parameters": [
{
"name": "path",
"type": "string"
},
{
"name": "maxAge",
"type": "integer"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm metacache ==
=== doveadm metacache clean ===

clean metacache content for given user or all users

parameters:

<nowiki>
{

"command": "metacacheClean",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "days",
"type": "integer"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache flush ===

flush metacache contents to storage for given user or all users

parameters:

<nowiki>
{
"command": "metacacheFlush",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache unpack ===

unpack metacache index bundle to target directory

parameters:

<nowiki>
{
"command": "metacacheUnpack",
"parameters": [
{
"name": "bundleName",
"type": "string"
},
{
"name": "bundle",
"type": "string"
},
{
"name": "destinationDirectory",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache flushall ===

flush metacache to storage for all users

parameters:

<nowiki>
{
"command": "metacacheFlushall",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache remove ===

remove metacache for given mask

parameters:

<nowiki>
{
"command": "metacacheRemove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "mask",
"type": "string"
}
]
}
</nowiki>
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache list ===

list local metacache contents

parameters:

<nowiki>
{
"command": "metacacheList",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm obox user delete ==

delete user data from storage, Cassandra and local caches (metacache and fscache).

parameters:

<nowiki>
{
"command": "oboxUserDelete",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

example:

<nowiki>
[
[
"oboxUserDelete",
{
"allUsers": 0,
"socketPath": "",
"user": "testuser003",
"userFile": ""
},
"aa"
]
]

# curl -v -u doveadm:hellodoveadm -X POST http://localhost:ype: application/json" -d '[["oboxUserDelete", {"allUsers":0,"user":"testuser003"}, "aa"]]'
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"aa"
]
]

CLI: doveadm obox user delete –u testuser003
</nowiki>

== doveadm sieve ==

Commands related to handling Sieve scripts.

=== doveadm sieve list ===

list user sieve scripts

parameters:

<nowiki>
{
"command": "sieveList",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve get ===

get user sieve script

parameters:

<nowiki>
{
"command": "sieveGet",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "scriptname",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve put ===

inject sieve script to user

parameters:

<nowiki>
{
"command": "sievePut",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "activate",
"type": "boolean"
},
{
"name": "scriptname",
"type": "string"
},
{
"name": "file",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve delete ===

delete user sieve

parameters:

<nowiki>
{
"command": "sieveDelete",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "ignoreActive",
"type": "boolean"
},
{
"name": "scriptname",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve activate ===

activate user sieve script

parameters:

<nowiki>
{
"command": "sieveActivate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "scriptname",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve deactivate ===

deactivate user sieve

parameters:

<nowiki>
{
"command": "sieveDeactivate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve rename ===

rename user sieve script

parameters:

<nowiki>
{
"command": "sieveRename",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "oldname",
"type": "string"
},
{
"name": "newname",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm fts ==
Dovecot fts indexing commands.

=== doveadm fts lookup ===

query user fts indexed data

parameters:

<nowiki>
{
"command": "ftsLookup",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts expand ===

<nowiki>
{
"command": "ftsExpand",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts tokenize ===

<nowiki>
{
"command": "ftsTokenize",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "language",
"type": "string"
},
{
"name": "text",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts optimize ===

<nowiki>
{
"command": "ftsOptimize",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts rescan ===

<nowiki>
{
"command": "ftsRescan",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

Template:DoveadmHTTPapi

2017-03-15T12:01:23Z

Oskarikentta: /* doveadm director move */

== Table of Contents ==
__TOC__

== 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:

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

=== 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:

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

Basic auth usage:
<nowiki>
curl -H "Authorization: Basic <base64 doveadm:doveadm_password>"
http://host:port/doveadm/v1
</nowiki>
or by letting curl to form the base64 encoded authentication basig authentication header:

<nowiki>
curl –u doveadm:password http://host:port/doveadm/v1
</nowiki>

=== 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:

<nowiki>

[
[
"command1",
{
"parameter1": "value",
"parameter2": "value",
"parameter3": "value"
},
"identifier"
]
]
</nowiki>
Multiple commands can be submitted in one json payload:
<nowiki>
[
[
"command1",
{
"parameter1": "value",
"parameter2": "value"
},
"identifier1"
],
[
"command2",
{
"parameter1": "value",
"parameter2": "value"
},
"identifier2"
]
]
</nowiki>

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:

<nowiki>

son payload:

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

</nowiki>

submitting the command with curl:

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

command line equivalent

doveadm reload

=== successful response ===

<nowiki>

[
[
"doveadmResponse",
[],
"a2"
]
]
</nowiki>

=== failure response ===

<nowiki>

[
[
"error",
{
"exitCode": 68,
"type": "exitCode"
},
"a2"
]
</nowiki>

=== failure codes ===

{| class="wikitable"
|-
|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
|}

== Supported commands ==

== doveadm service ==
=== doveadm service stop ===

stop one or more dovecot services on target host

<nowiki>
{
"command": "serviceStop",
"parameters": [
{
"name": "service",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|service
|string array
|Name of service to stop
|[“imap”,”imap-hibernate”]
|}

example:

<nowiki>
[
[
"serviceStop",
{
"service": [
"imap",
"imap-hibernate"
]
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["serviceStop",{"service":["imap","imap-hibernate"]},"aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm service stop imap imap-hibernate
</nowiki>

=== doveadm stop ===

stop dovecot on the target host
<nowiki>

{
"command": "stop",
"parameters": []
}

no parameters
</nowiki>
example:
<nowiki>
[
[
"stop",
{},
"a1"
]
]

# curl -u doveadm:hellodoveadm -X POST http://localhost:8080/doveadm/v1 -H "Content-Type: application/json" -d '[["stop",{},"a1"]]'

CLI: doveadm stop
</nowiki>

=== doveadm reload ===

reload dovecot configuration

<nowiki>
{
"command": "reload",
"parameters": []
}
</nowiki>

example:

<nowiki>
[
[
"reload",
{},
"a2"
]
]

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

CLI: doveadm reload
</nowiki>

== doveadm stats ==
=== doveadm stats dump ===

dump collected dovecot statistics

<nowiki>
{
"command": "statsDump",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "type",
"type": "string"
},
{
"name": "filter",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|+parameters
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|type
|String
|Type of stats to dump
|global
|-
|filter
|String
|Dump filter
|last_update 1483101542
|}

Example:

<nowiki>
[
[
"statsDump",
{
"type": "global"
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["statsDump",{"type":"global"},"aa"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"auth_cache_hits": "0",
"auth_cache_misses": "0",
"auth_db_tempfails": "0",
"auth_failures": "0",
"auth_master_successes": "0",
"auth_successes": "0",
"clock_time": "0.0",
"disk_input": "0",
"disk_output": "0",
"fscache_read": "0",
"fscache_stat": "0",
"fscache_write": "0",
"idx_del": "0",
"idx_iter": "0",
"idx_read": "0",
"idx_read_usecs": "0",
"idx_wbytes": "0",
"idx_write": "0",
"idx_write_usecs": "0",
"invol_cs": "0",
"last_update": "0.000000",
"mail_cache_hits": "0",
"mail_lookup_attr": "0",
"mail_lookup_path": "0",
"mail_read_bytes": "0",
"mail_read_count": "0",
"maj_faults": "0",
"min_faults": "0",
"num_cmds": "0",
"num_connected_sessions": "0",
"num_logins": "0",
"obox_copy": "0",
"obox_del": "0",
"obox_iter": "0",
"obox_read": "0",
"obox_read_usecs": "0",
"obox_stat": "0",
"obox_wbytes": "0",
"obox_write": "0",
"obox_write_usecs": "0",
"read_bytes": "0",
"read_count": "0",
"reset_timestamp": "1483104199",
"sys_cpu": "0.0",
"user_cpu": "0.0",
"vol_cs": "0",
"write_bytes": "0",
"write_count": "0"
}
],
"aa"
]
]

CLI: doveadm stats dump global
</nowiki>

=== doveadm stats reset ===
reset dovecot statistics counters
<nowiki>

{
"command": "statsReset",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|}

example:

<nowiki>
[
[
"statsReset",
{},
"aa"
]
]

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

CLI: doveadm stats reset
</nowiki>

== doveadm penalty ==

<nowiki>
show current penalties

{
"command": "penalty",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "netmask",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|string
|Path to doveadm socket
|/var/run/dovecot-server
|-
|netmask
|string
|To reduce/filter the output supply an IP address or a network range in CIDR notation (ip/mask)
|10.0.0.0/24
|}

example:

<nowiki>
[
[
"penalty",
{},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["penalty",{},"aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm penalty
</nowiki>

== doveadm kick ==

Kick user from dovecot. Applicable to session in dovecot backend only

<nowiki>
{
"command": "kick",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "force",
"type": "boolean"
},
{
"name": "mask",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|force
|Boolean
|Do a forced kick?
|0
|-
|mask
|String
|Uid mask
|testuser001
|}

example:

<nowiki>
[
[
"kick",
{
"force": 0,
"mask": "testuser001"
},
"aa"
]
]

# curl -v -u doveadm:hellodoveadm –H “Content-Type: application/json" -d '[["kick", {"mask":"testuser001"}, "aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm kick testuser001
</nowiki>

response for succesfull kick:

<nowiki>
[
[
"doveadmResponse",
[
{
"result": "testuser001"
}
],
"aa"
]
]
</nowiki>

response in case kick failed:

<nowiki>
[
[
"error",
{
"exitCode": 68,
"type": "exitCode"
},
"aa"
]
]
</nowiki>

== doveadm who ==

<nowiki>
list active dovecot sessions

{
"command": "who",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "separateConnections",
"type": "boolean"
},
{
"name": "mask",
"type": "array"
}
]
}
</nowiki>

parameters

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|string
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|separateConnections
|Boolean
|Show each user connection in separate entries
|0
|-
|mask
|string array
|Uid mask
|testuser001
|}

Example:

<nowiki>
[
[
"who",
{
"mask": "",
"separateConnections": 0,
"socketPath": ""
},
"aa"
]
]

# curl -v -u doveadm:hellodoveadm -X POST http://localhost:ype: application/json" -d '[["who", {}, "aa"]]' http://localhost:8080/doveadm/v1

CLI: doveadm who
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"connections": "1",
"ips": "(127.0.0.1)",
"pids": "(4999)",
"service": "imap",
"username": "testuser001"
}
],
"aa"
]
]
</nowiki>

== doveadm director ==
=== doveadm director status ===

Show backend statuses on directors. Available only in directors

<nowiki>
[
{
"command": "directorStatus",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "tag",
"type": "string"
}
]
}
]
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|String
|Show director status for Tagged hosts only
|NewBackend
|}

example:

<nowiki>
[
[
"directorStatus",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorStatus",{},"bb"]]' http://localhost:8080/doveadm/v1

</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"mail server ip": "10.0.0.234",
"state": "up",
"state-changed": "2016-12-15 08:31:37",
"tag": "",
"users": "1",
"vhosts": "100"
},
{
"mail server ip": "10.0.0.235",
"state": "up",
"state-changed": "2016-12-15 08:31:04",
"tag": "",
"users": "0",
"vhosts": "100"
}
],
"bb"
]
]

CLI: doveadm director status
</nowiki>

=== doveadm director map ===

list current user → host mappings. Applicable to director only

<nowiki>

"command": "directorMap",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "usersFile",
"type": "string"
},
{
"name": "hashMap",
"type": "boolean"
},
{
"name": "userMap",
"type": "boolean"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

parameters

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|usersFile
|String
|provide Path to users list. One username per line
|/etc/dovecot/userlist.txt
|-
|hashMap
|Boolean
|Output users as hashmap
|True
|-
|userMap
|Boolean
|Output users as userlist
|True
|-
|host
|String
|Show only mappings to given host
|10.0.0.234
|}

example:

<nowiki>
[
[
"directorMap",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorMap",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"expire time": "2016-12-30 14:52:56",
"hash": "3853430566",
"mail server ip": "10.0.0.235",
"user": "samik"
}
],
"bb"
]
]

CLI: doveadm director map
</nowiki>

=== doveadm director add ===

add backend to director ring

<nowiki>
{
"command": "directorAdd",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "tag",
"type": "string"
},
{
"name": "host",
"type": "string"
},
{
"name": "vhostCount",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|tag
|String
|apply tag to backend
|/etc/dovecot/userlist.txt
|-
|host
|String
|backend ip to add
|10.0.0.234
|-
|vhostCount
|String
|vhost count to add
|100
|}

Example:

<nowiki>
[
[
"directorAdd",
{
"host": "10.0.234"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorAdd",{"host":"10.0.234"},"bb"]]' http://localhost:8080/doveadm/v1

CLI: doveadm director add 10.0.0.234
</nowiki>

=== doveadm director update ===

<nowiki>
{
"command": "directorUpdate",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
},
{
"name": "vhostCount",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|string
|Show director status for tagged hosts only
|NewBackend
|}

=== doveadm director up ===

<nowiki>
{
"command": "directorUp",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|string
|Show director status for tagged hosts only
|NewBackend
|}

=== doveadm director down ===

<nowiki>
{
"command": "directorDown",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|Show hashed status for individual user
|testuser001
|-
|tag
|string
|Show director status for tagged hosts only
|NewBackend
|}

=== doveadm director remove ===

remove backend from director ring

<nowiki>
{
"command": "directorRemove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|host
|String
|backend to remove
|10.0.0.134
|}

example:

<nowiki>
[
[
"directorRemove",
{
"host": "10.0.0.234"
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRemove",{"host":"10.0.0.234"},"aa"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"aa"
]
]

CLI: doveadm director remove 10.0.0.234
</nowiki>

=== doveadm director move ===

move user mapping from backend to another or create director mapping for an user
<nowiki>
{
"command": "directorMove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|user
|String
|User uid to move
|testuser001
|-
|host
|string
|Target backend ip as listed in doveadm doveadm director status
|10.0.0.234
|}

example:

<nowiki>
[
[
"directorMove",
{
"host": "10.0.234",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorMove",{"user":"samik","host":"10.0.234"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director move samik 10.0.0.234
</nowiki>

== doveadm director kick ==

<nowiki>
{
"command": "directorKick",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
| Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|user
|String
|uid of user to kick
|samik
|}

example:

<nowiki>
[
[
"directorKick",
{
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorKick",{"user":"samik"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director kick samik
</nowiki>

=== doveadm director flush ===

flush connection mappings to one backend at director level. All users mapped to given host will be flushed from the hashmap table and will be redistributed to backends.

Parameters:

<nowiki>
{
"command": "directorFlush",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "forceFlush",
"type": "boolean"
},
{
"name": "host",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|forceFlush
|Boolean
|Flag to make flush forced
|True
|-
|host
|String
|Backend ip address from doveadm director status list
|10.0.0.234
|}

example:

<nowiki>
[
[
"directorFlush",
{
"host": "10.0.0.234"
},
"aa"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorFlush",{"host":"10.0.0.234"},"aa"]]' http://localhost:8080/doveadm/v1

</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"aa"
]
]
CLI: doveadm director flush 10.0.234
</nowiki>

=== doveadm director dump ===

Dumb the current director backend host configuration as commands

<nowiki>
{
"command": "directorDump",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|}

example:

<nowiki>
[
[
"directorDump",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorDump",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"command": "add",
"host": "10.0.0.234",
"socket-path": "/var/run/dovecot/director-admin",
"vhost_count": "100"
},
{
"command": "add",
"host": "10.0.0.235",
"socket-path": "/var/run/dovecot/director-admin",
"vhost_count": "100"
}
],
"bb"
]
]

CLI: doveadm director dump
</nowiki>

=== doveadm director ring add ===

add new director to director ring

parameters:

<nowiki>
{
"command": "directorRingAdd",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "ip",
"type": "string"
},
{
"name": "port",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|ip
|String
|director ip address to add
|10.0.0.233
|-
|port
|String
|port number to use if not default
|9143
|}

example:

<nowiki>
[
[
"directorRingAdd",
{
"ip": "10.0.0.233"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRingAdd",{"ip":"10.0.0.233"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director ring add 10.0.0.233
</nowiki>

=== doveadm director ring remove ===

remove director from director ring

parameters:

<nowiki>
{
"command": "directorRingRemove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "ip",
"type": "string"
},
{
"name": "port",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|-
|ip
|String
|director ip to remove
|10.0.0.233
|-
|port
|String
|director service port if not default
|9143
|}

example:

<nowiki>
[
[
"directorRingRemove",
{
"ip": "10.0.0.233"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRingRemove",{"ip":"10.0.0.233"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm director ring remove 10.0.0.233
</nowiki>

=== doveadm director ring status ===

show director ring status

parameters:

<nowiki>

{
"command": "directorRingStatus",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/director-admin
|}

example:

<nowiki>
[
[
"directorRingStatus",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["directorRingStatus",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>

[
"doveadmResponse",
[
{
"director ip": "10.0.0.232",
"last failed": "never",
"port": "9143",
"status": "synced",
"type": "self"
},
{
"director ip": "10.0.0.233",
"last failed": "never",
"port": "9143",
"status": "",
"type": ""
}
],
"bb"
]
]

CLI: doveadm director ring status
</nowiki>

== doveadm proxy ==

The doveadm proxy commands are used to list or kick active Dovecot proxy connections.

=== doveadm proxy list ===

list active connections in the dovecot proxy

parameters:

<nowiki>
{
"command": "proxyList",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|}

example:

<nowiki>
[
[
"proxyList",
{},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["proxyList",{},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"dest-ip": "127.0.0.1",
"dest-port": "1143",
"service": "imap",
"src-ip": "10.0.0.153",
"username": "samik"
}
],
"bb"
]
]

CLI: doveadm proxy list
</nowiki>

=== doveadm proxy kick ===

kick user session from proxy. applicable to imap/pop3/managesieve sessions

parameters:

<nowiki>
{
"command": "proxyKick",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|userid to kick
|samik
|}

example:

<nowiki>
[
[
"proxyKick",
{
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["proxyKick",{"user":"samik"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"count": "1"
}
],
"bb"
]
]

CLI: doveadm proxy kick samik
</nowiki>

== doveadm logs errors ==

fetch errors log

paraments:

<nowiki>
{
"command": "logErrors",
"parameters": [
{
"name": "since",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|}

example:

<nowiki>
[
[
"logErrors",
{},
"a2"
]
]

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

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"prefix": "stats",
"text": "Stats client input error: Invalid level",
"timestamp": "Dec 09 16:24:00",
"type": "Error"
},
{
"prefix": "doveadm(127.0.0.1)",
"text": "read(/var/run/dovecot/stats) unexpectedly disconnected",
"timestamp": "Dec 09 16:24:00",
"type": "Fatal"
},
{
"prefix": "stats",
"text": "Stats client input error: Invalid level",
"timestamp": "Dec 09 16:24:22",
"type": "Error"
},
{
"prefix": "stats",
"text": "Stats client input error: Invalid level",
"timestamp": "Dec 09 16:27:48",
"type": "Error"
},
{
"prefix": "director",
"text": "Empty server list",
"timestamp": "Dec 09 16:29:13",
"type": "Error"
},
{
"prefix": "director",
"text": "Invalid value for director_mail_servers setting",
"timestamp": "Dec 09 16:29:13",
"type": "Fatal"
}
],
"a2"
]
]

CLI: doveadm log errors
</nowiki>

== doveadm dict ==
=== doveadm dict get ===

get user key value from configured dictionary

parameters:

<nowiki>
{
"command": "dictGet",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to query
|samik
|-
|dictUri
|String
|optional URI for dictionary to query
|
|-
|key
|String
|key to query
|
|}

=== doveadm dict set ===

set user key value in configured dictionary

parameters:

<nowiki>
{
"command": "dictSet",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
},
{
"name": "value",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|samik
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|key
|String
|dictionary key to modify
|
|-
|value
|string
|value to set
|
|}

=== doveadm dict unset ===

unset user key value in configured dictionary

parameters:

<nowiki>
{
"command": "dictUnset",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|key
|String
|dictionary key to unset
|
|}
== doveadm dict inc ==

increase users key value in dictionary

parameters:

<nowiki>
{
"command": "dictInc",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "key",
"type": "string"
},
{
"name": "difference",
"type": "integer"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|optional URI for dictionary to modify
|
|-
|key
|String
|dictionary key to increase
|
|-
|difference
|integer
|increment value
|
|}

=== doveadm dict iter ===

list user keys in dictionary

parameters:

<nowiki>
{
"command": "dictIter",
"parameters": [
{
"name": "user",
"type": "string"
},
{
"name": "exact",
"type": "boolean"
},
{
"name": "recurse",
"type": "boolean"
},
{
"name": "noValue",
"type": "boolean"
},
{
"name": "dictUri",
"type": "string"
},
{
"name": "prefix",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid of user to modify dictionary key
|
|-
|dictUri
|String
|optional URI for dictionary to modify
|
|-
|exact
|Boolean
|list only exact matches
|
|-
|recurce
|Boolean
|do recursive search
|
|-
|noValue
|Boolean
|list also keys that have no value set
|
|-
|prefix
|String
|search only keys with given prefix
|
|}

== doveadm fs ==
=== doveadm fs get ===

get object from storage

parameters:

<nowiki>
{
"command": "fsGet",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem to fetch
|
|}

=== doveadm fs put ===

put object to storage

parameters:

<nowiki>
{
"command": "fsPut",
"parameters": [
{
"name": "hash",
"type": "string"
},
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "inputPath",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|hash
|string
|
|
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|inputPath
|String
|source object path in local filesystem
|
|-
|path
|String
|object path filesystem to put
|
|}

=== doveadm fs copy ===

copy object in storage

parameters:

<nowiki>
{
"command": "fsCopy",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "sourcePath",
"type": "string"
},
{
"name": "destinationPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|sourcePathh
|String
|source object path
|
|-
|Destination path
|String
|destination object path in filesystem
|
|}

=== doveadm fs stat ===

fetch fs driver statistics

parameters:

<nowiki>
{
"command": "fsStat",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem fetch statistics for
|
|}

=== doveadm fs metadata ===

get filesystem object metadata

parameters:

<nowiki>
{
"command": "fsMetadata",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem fetch statistics for
|
|}

=== doveadm fs delete ===

delete object from storage

<nowiki>
{
"command": "fsDelete",
"parameters": [
{
"name": "recursive",
"type": "boolean"
},
{
"name": "maxParallel",
"type": "integer"
},
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|object path in filesystem fetch statistics for
|
|-
|recursive
|Boolean
|do a recursive delete of path
|
|-
|maxParallel
|integer
|max number of parallel workers
|
|}

=== doveadm fs iter ===

list objects in given fs path

parameters:

<nowiki>
{
"command": "fsIter",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|path in filesystem to list
|
|}

=== doveadm fs iter-dirs ===
ist subfolders in given path

parameters:

<nowiki>
{
"command": "fsIterDirs",
"parameters": [
{
"name": "fsDriver",
"type": "string"
},
{
"name": "fsArgs",
"type": "string"
},
{
"name": "path",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|fsDriver
|String
|filesystem driver to use
|
|-
|fsArgs
|String
|filesystem driver arguments to use
|
|-
|path
|String
|path in filesystem to list for subfolders
|
|}

== doveadm auth cache flush ==

flush authentication cache for one user or all users

parameters:

<nowiki>
{
"command": "authCacheFlush",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String array
|optional list of users in flush
|[“samik”,”samitest”]
|}

example:

<nowiki>
[
[
"authCacheFlush",
{
"user": [
"samik"
]
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["authCacheFlush",{"user":["samik"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"entries": "0"
}
],
"bb"
]
]

CLI: doveadm auth cache flush samik
</nowiki>

== doveadm user ==

do a userdb lookup for an user

<nowiki>
{
"command": "user",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "authInfo",
"type": "array"
},
{
"name": "field",
"type": "string"
},
{
"name": "expandField",
"type": "string"
},
{
"name": "userdbOnly",
"type": "boolean"
},
{
"name": "userMask",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|authInfo
|String array
|auth_info specifies additional conditions for the user command. The auth_info option string has to be given as name=value pair. For multiple conditions the -x option could be supplied multiple times.
Possible names for the auth_info are:
service
The service for which the userdb lookup should be tested. The value may be the name of a service, commonly used with Dovecot. For example: imap, pop3 or smtp.
lip
The local IP address (server) for the test.
rip
The remote IP address (client) for the test.
lport
The local port, e.g. 143
rport
The remote port, e.g. 24567
|sevice=imap
|-
|field
|String
|fetch only one specified field instead of all
|
|-
|expandField
|String
|expand configuration variable with user specific values
|
|-
|userdbOnly
|Boolean
|only fetch from userdb lookup and don’t process passdb
|
|-
|userMask
|String array
|search filter
|
|}

example:

<nowiki>
[
[
"user",
{
"userMask": [
"samik"
]
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["user",{"userMask":["samik"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
{
"samik": {
"gid": "1000",
"home": "/var/vmail/samik",
"junkflag": "0",
"mail": "Maildir:/mails/mails/samik/Maildir",
"namespace/Junk/hidden": "no",
"namespace/Junk/list": "yes",
"uid": "1000"
}
},
"bb"
]
]

CLI: doveadm user samik
</nowiki>

== doveadm mailbox ==
=== doveadm mailbox metadata set ===

set user mailbox metadata

parameters:

<nowiki>
{
"command": "mailboxMetadataSet",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "key",
"type": "string"
},
{
"name": "value",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata set
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to set
|
|-
|value
|String
|metadata value to set
|
|}

example:

<nowiki>
[
[
"mailboxMetadataSet",
{
"key": "/private/comment",
"mailbox": "INBOX",
"user": "samik",
"value": "test"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataSet",{"user":"samik","mailbox":"INBOX","key":"/private/comment","value":"test"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox metadata set –u samik INBOX /private/comment test
</nowiki>

=== doveadm mailbox metadata unset ===

unset user mailbox metadata

parameters:

<nowiki>
{
"command": "mailboxMetadataUnset",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata unset
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to unset
|
|}

example:

<nowiki>
[
[
"mailboxMetadataUnset",
{
"key": "/private/comment",
"mailbox": "INBOX",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataUnset",{"user":"samik","mailbox":"INBOX","key":"/private/comment"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox metadata unset –u samik INBOX /private/comment
</nowiki>

=== doveadm mailbox metadata get ===

get user mailbox metadata

parameters:

<nowiki>
{
"command": "mailboxMetadataGet",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "key",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata get
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to get
|
|}

example:

<nowiki>
[
[
"mailboxMetadataGet",
{
"key": "/private/comment",
"mailbox": "INBOX",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataGet",{"user":"samik","mailbox":"INBOX","key":"/private/comment"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response

<nowiki>
[
[
"doveadmResponse",
[
{
"value": "plaa"
}
],
"bb"
]
]

CLI: doveadm mailbox metadata get –u samik INBOX /private/comment
</nowiki>

=== doveadm mailbox list ===

list user mailbox metadata for a folder

parameters:

<nowiki>

"command": "mailboxMetadataList",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "keyPrefix",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply metadata get
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|key
|String
|metadata key to get
|
|-
|keyPrefix
|String
|search prefix for keys
|
|-
|mailbox
|String
|mailbox to fetch metadata from
|
|}

example:

<nowiki>
[
[
"mailboxMetadataList",
{
"mailbox": "INBOX",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxMetadataList",{"user":"samik","mailbox":"INBOX"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"key": "comment"
},
{
"key": "specialuse"
}
],
"bb"
]
]

CLI: doveadm mailbox metadata list –u samik INBOX
</nowiki>

=== doveadm mailbox status ===

fetch user mailbox status

parameters:

<nowiki>
{
"command": "mailboxStatus",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "totalSum",
"type": "boolean"
},
{
"name": "field",
"type": "array"
},
{
"name": "mailboxMask",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply status fetch
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|totalSum
|boolean
|
|
|-
|field
|String array
|fields to fetch
|all
|-
|mailboxMask
|String array
|fetch status on given mailboxes
|
|}

example:

<nowiki>

[
[
"mailboxStatus",
{
"field": [
"all"
],
"mailboxMask": [
"INBOX",
"INBOX/*",
"*"
],
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxStatus",{"user":"samik","field":["all"],"mailboxMask":["INBOX","INBOX/*","*"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"guid": "21b588150b156558eb3500007afd792c",
"highestmodseq": "5",
"mailbox": "Junk",
"messages": "0",
"recent": "0",
"uidnext": "1",
"uidvalidity": "1483019529",
"unseen": "0",
"vsize": "0"
},
{
"guid": "21b588150b156558eb3500007afd792c",
"highestmodseq": "5",
"mailbox": "INBOX",
"messages": "0",
"recent": "0",
"uidnext": "1",
"uidvalidity": "1483019529",
"unseen": "0",
"vsize": "0"
}
],
"bb"
]
]

CLI: doveadm mailbox status –u samik all “*”
</nowiki>

=== doveadm mailbox list ===

fetch user folder list

parameters:

<nowiki>
{
"command": "mailboxList",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mutf7",
"type": "boolean"
},
{
"name": "utf8",
"type": "boolean"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "mailboxMask",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|user
|String
|uid to apply mailbox list
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|mutf7
|Boolean
|
|
|-
|utf8
|Boolean
|fetch only certain fields instead of all
|
|-
|subscription
|Boolean
|
|
|-
|mailboxMask
|String array
|fetch list of given mailboxes
|
|}

example:

<nowiki>
[
[
"mailboxList",
{
"user": "samik"
},
"bb"
]
]
# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxList",{"user":"samik"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"mailbox": "Junk"
},
{
"mailbox": "INBOX"
}
],
"bb"
]
]

CLI: doveadm mailbox list –u samik
</nowiki>

=== doveadm mailbox create ===
create mailbox folder for user

parameters:

<nowiki>
{
"command": "mailboxCreate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "guid",
"type": "string"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply mailbox create
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|subscription
|Boolean
|
|
|-
|mailbox
|String array
|list of mailbox folders to create
|
|}

example:

<nowiki>
[
[
"mailboxCreate",
{
"mailbox": [
"INBOX/myfolder"
],
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxCreate",{"user":"samik","mailbox":["INBOX/myfolder"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>

[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox create –u samik INBOX/myfolder
</nowiki>

=== doveadm mailbox delete ===

delete user mailbox folder

parameters:

<nowiki>
{
"command": "mailboxDelete",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "requireEmpty",
"type": "boolean"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "recursive",
"type": "boolean"
},
{
"name": "unsafe",
"type": "boolean"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply delete
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|requireEmpty
|Boolean
|only delete if folder is empty
|
|-
|subscription
|Boolean
|
|
|-
|recursive
|Boolean
|delete also subfolders
|
|-
|unsafe
|Boolean
|
|
|-
|mailbox
|String array
|list of mailbox folders to create
|
|}

example:

<nowiki>
[
[
"mailboxDelete",
{
"mailbox": [
"INBOX/myfolder"
],
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxDelete",{"user":"samik","mailbox":["INBOX/myfolder"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox delete –u samik INBOX/myfolder
</nowiki>

=== doveadm mailbox rename ===

rename user folder

parameters:

<nowiki>
{
"command": "mailboxRename",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "subscriptions",
"type": "boolean"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "newName",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply mailbox rename
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|subscriptions
|Boolean
|
|
|-
|newName
|String
|mailbox new name
|
|-
|mailbox
|String
|mailbox to rename
|
|}

example:

<nowiki>
[
[
"mailboxRename",
{
"mailbox": "INBOX/myfolder",
"newName": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxRename",{"user":"samik","mailbox":"INBOX/myfolder","newName":"INBOX/myfoldertoo"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox rename –u samik INBOX/myfolder INBOX/myfoldertoo
</nowiki>

=== doveadm mailbox subscribe ===

subscribe user to a mailbox

parameters:

<nowiki>
{
"command": "mailboxSubscribe",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply subscribe
|
|-
|userFile
|String
|optionally fetch usernames from. One username per line
|
|-
|mailbox
|String
|mailbox to subscribe
|
|}

example:

<nowiki>
[
[
"mailboxSubscribe",
{
"mailbox": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxSubscribe",{"user":"samik","mailbox":"INBOX/myfoldertoo"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:
<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox subscribe –u samik INBOX/myfoldertoo
</nowiki>

=== doveadm mailbox unsubscribe ===

unsubscribe user from an folder

parameters:

<nowiki>
{
"command": "mailboxUnsubscribe",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply unsubscribe
|
|-
|userFile
|String
|optionally fetch usernames from. One username per line
|
|-
|mailbox
|String
|mailbox to unsubscribe
|
|}

example:

<nowiki>
[
[
"mailboxUnsubscribe",
{
"mailbox": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["mailboxUnsubscribe",{"user":"samik","mailbox":"INBOX/myfoldertoo"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm mailbox unsubscribe –u samik INBOX/myfoldertoo
</nowiki>

=== doveadm mailbox update ===

update user mailbox information

parameters:

<nowiki>
{
"command": "mailboxUpdate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailboxGuid",
"type": "string"
},
{
"name": "uidValidity",
"type": "string"
},
{
"name": "minNextUid",
"type": "string"
},
{
"name": "minFirstRecentUid",
"type": "string"
},
{
"name": "minHighestModseq",
"type": "string"
},
{
"name": "minHighestPvtModseq",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid to apply update
|
|-
|userFile
|String
|optionally fetch usernames from. One username per line
|
|-
|mailbox
|String
|mailbox to unsubscribe
|
|-
|mailboxGuid
|String
|set mailbox guid
|
|-
|uidValidity
|String
|set mailbox uidvalidity
|
|-
|minNextuid
|String
|set mailbox minimum next uid
|
|-
|minFirstRecentuid
|String
|set mailbox minimum recent uid
|
|-
|minHighestModseq
|String
|
|
|-
|minHighestPvtModseq
|String
|
|
|}

=== doveadm mailbox save ===

save mail into users mailbox

parameters:

<nowiki>
{
"command": "save",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailbox",
"type": "string"
},
{
"name": "file",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to save mail into
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|mailbox
|String
|mailbox to unsubscribe
|
|-
|file
|String
|mail to inject
|
|}

example:

<nowiki>
[
[
"save",
{
"file": "From: Joulu Pukki <joulu.pukki@korvatunturi.fi>\nSubject: plaa\n\nmail body\n",
"mailbox": "INBOX/myfoldertoo",
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["save",{"user":"samik","mailbox":"INBOX/myfoldertoo","file":"From: Joulu Pukki <joulu.pukki@korvatunturi.fi>\nSubject: plaa\n\nmail body\n"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]
</nowiki>

== doveadm fetch ==

fetch data from user mailbox

parameters:

<nowiki>
{
"command": "fetch",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "field",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to fetch data
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|field
|String array
|fields to fetch. Supported fields as of dovecot 2.2.26: hdr.<name> body.<section> binary.<section> user mailbox mailbox-guid seq uid guid flags modseq hdr body body.snippet text text.utf8 size.physical size.virtual date.received date.sent date.saved date.received.unixtime date.sent.unixtime date.saved.unixtime imap.envelope imap.body imap.bodystructure pop3.uidl pop3.order refcount storageid
|
|-
|query
|String array
|search query to user
|
|}

example:

<nowiki>
[
[
"fetch",
{
"field": [
"text"
],
"query": [
"mailbox",
"INBOX/myfoldertoo"
],
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["fetch",{"user":"samik","field":["text"],"query":["mailbox","INBOX/myfoldertoo"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"text": "From: Joulu Pukki <joulu.pukki@korvatunturi.fi>\nSubject: plaa\n\nmail body\n"
}
],
"bb"
]
]

CLI: doveadm fetch –u samik “text” mailbox INBOX/myfoldertoo
</nowiki>

== doveadm index ==

index user mailbox folder or folders

parameters:

<nowiki>
{
"command": "index",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "queue",
"type": "boolean"
},
{
"name": "maxRecent",
"type": "string"
},
{
"name": "mailboxMask",
"type": "string"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to index
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|query
|Boolean
|max number of recent mails to index
|
|-
|maxRecent
|String
|max number of recent mails to index
|
|-
|mailboxMask
|String
|mailbox search mask to apply indexing into
|
|}

example:

<nowiki>
[
[
"index",
{
"mailboxMask": "INBOX*",
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["index",{"user":"samik","mailboxMask":"INBOX*"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm index –u samik “INBOX*”
</nowiki>

== doveadm altmove ==

move mails between primary and alternative mailbox storage locations. Applicable to mdbox and sdbox mailbox formats only

parameters:

<nowiki>
{
"command": "altmove",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "reverse",
"type": "boolean"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to apply move
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|reverse
|Boolean
|search query to apply to mail move
|
|-
|query
|String array
|search query to apply to mail move
|
|}

example:

<nowiki>
[
[
"altmove",
{
"query": [
"mailbox",
"INBOX/myfoldertoo",
"savedbefore",
"since",
"30d"
],
"reverse": 0,
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["altmove",{"user":"samik","reverse":0,"query":["mailbox","INBOX/myfoldertoo","savedbefore","since","30d"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

== doveadm deduplicate ==

This command is used to expunge duplicated messages in mailboxes

parameters:

<nowiki>
{
"command": "deduplicate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "byMsgid",
"type": "boolean"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to deduplicate
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|byMsgId
|Boolean
|deduplicate by Message-ID instead of guid
|
|-
|query
|String array
|search query to apply to deduplicate
|
|}

== doveadm expunge ==

Expunge messages matching given search query

parameters:

<nowiki>
{
"command": "expunge",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "deleteEmptyMailbox",
"type": "boolean"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to expunge
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|deleteEmptyMailbox
|Boolean
|delete also mailbox if it’s empty after expunge has been applied
|
|-
|query
|String array
|search query to apply to expunge
|
|}

== doveadm flags ==
add, remove or replace messages' flags

=== doveadm flags add ===

add flag to a message or messages

parameters:

<nowiki>
{
"command": "flagsAdd",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "flag",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to add flags
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|flag
|String array
|list of flags to add
|
|-
|query
|String array
|search query to apply to flag add
|
|}

=== doveadm flags remove ===

remove flags from message or messages

parameters:

<nowiki>
{
"command": "flagsRemove",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "flag",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to add flags
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|flag
|String array
|list of flags to remove
|
|-
|query
|String array
|search query to apply to flag remove
|
|}

=== doveadm flags replace ===

Replace flags with another flag in message or messages. Replaces all current flags with the ones in the parameter list

parameters:

<nowiki>
{
"command": "flagsReplace",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "flag",
"type": "array"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to replace flags
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|flag
|String array
|list of flags to replace with
|
|-
|query
|String array
|search query to apply to flag replace
|
|}

== doveadm import ==

Import messages matching given search query

parameters:

<nowiki>
{
"command": "import",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "subscribe",
"type": "boolean"
},
{
"name": "sourceLocation",
"type": "string"
},
{
"name": "destParentMailbox",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to apply import
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|subscribe
|boolean
|when enabled possible newly created folders are also subscibed
|
|-
|sourceLocation
|String
|location of source mailboxes
|
|-
|destParentMailbox
|String
|destination parent mailbox where to import
|
|-
|query
|String array
|search query for messages to import
|
|}

== doveadm force-resync ==

Under certain circumstances it may happen, that dovecot is unable to automatically solve problems with mailboxes. In such situations the force-resync command may be helpful. It tries to fix all problems. For sdbox and mdbox mailboxes the storage files will be also checked.

parameters:

<nowiki>
{
"command": "forceResync",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "mailboxMask",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|user
|String
|uid of user to apply resync
|
|-
|mailboxMask
|String
|apply forced resync on given mailboxes
|INBOX*
|}

example:

<nowiki>
[
[
"forceResync",
{
"mailboxMask": "INBOX*",
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["forceResync",{"user":"samik","mailboxMask":"INBOX*"},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"bb"
]
]

CLI: doveadm force-resync –u samik “INBOX*”
</nowiki>

== doveadm purge ==

Remove messages with refcount=0 from mdbox files

parameters:

<nowiki>
{
"command": "purge",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|user
|String
|uid of user to apply purge
|
|}

== doveadm search ==

Show a list of mailbox GUIDs and message UIDs matching given search query

parameters:

<nowiki>
{
"command": "search",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|allUsers
|Boolean
|apply operation to all users
|
|-
|userFile
|String
|optionally fetch usernames from file. One username per line
|
|-
|user
|String
|uid of user to apply purge
|
|-
|query
|String array
|search query
|
|}

example:

<nowiki>
[
[
"search",
{
"query": [
"mailbox",
"INBOX*",
"all"
],
"user": "samik"
},
"bb"
]
]

# curl -v -X POST -u doveadm:hellodoveadm -H "Content-Type: application/json" -d '[["search",{"user":"samik","query":["mailbox","INBOX*","all"]},"bb"]]' http://localhost:8080/doveadm/v1
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[
{
"mailbox-guid": "cf497f128caf7c58612200007afd792c",
"uid": "1"
}
],
"bb"
]
]

CLI: doveadm search –u samik mailbox “INBOX*” all
</nowiki>

== doveadm copy ==

Copy messages matching the given search query into another mailbox

parameters:

<nowiki>
{
"command": "copy",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "destinationMailbox",
"type": "string"
},
{
"name": "sourceType",
"type": "string"
},
{
"name": "sourceUser",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm move ==

Move messages matching the given search query into another mailbox

parameters:

<nowiki>
{
"command": "move",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "destinationMailbox",
"type": "string"
},
{
"name": "sourceType",
"type": "string"
},
{
"name": "sourceUser",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm fscache rescan ==

force fscache rescan

parameters:

<nowiki>
{
"command": "fscacheRescan",
"parameters": [
{
"name": "path",
"type": "string"
},
{
"name": "maxAge",
"type": "integer"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm metacache ==
=== doveadm metacache clean ===

clean metacache content for given user or all users

parameters:

<nowiki>
{

"command": "metacacheClean",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "days",
"type": "integer"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache flush ===

flush metacache contents to storage for given user or all users

parameters:

<nowiki>
{
"command": "metacacheFlush",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache unpack ===

unpack metacache index bundle to target directory

parameters:

<nowiki>
{
"command": "metacacheUnpack",
"parameters": [
{
"name": "bundleName",
"type": "string"
},
{
"name": "bundle",
"type": "string"
},
{
"name": "destinationDirectory",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache flushall ===

flush metacache to storage for all users

parameters:

<nowiki>
{
"command": "metacacheFlushall",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache remove ===

remove metacache for given mask

parameters:

<nowiki>
{
"command": "metacacheRemove",
"parameters": [
{
"name": "socketPath",
"type": "string"
},
{
"name": "mask",
"type": "string"
}
]
}
</nowiki>
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm metacache list ===

list local metacache contents

parameters:

<nowiki>
{
"command": "metacacheList",
"parameters": [
{
"name": "socketPath",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm obox user delete ==

delete user data from storage, Cassandra and local caches (metacache and fscache).

parameters:

<nowiki>
{
"command": "oboxUserDelete",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

example:

<nowiki>
[
[
"oboxUserDelete",
{
"allUsers": 0,
"socketPath": "",
"user": "testuser003",
"userFile": ""
},
"aa"
]
]

# curl -v -u doveadm:hellodoveadm -X POST http://localhost:ype: application/json" -d '[["oboxUserDelete", {"allUsers":0,"user":"testuser003"}, "aa"]]'
</nowiki>

response:

<nowiki>
[
[
"doveadmResponse",
[],
"aa"
]
]

CLI: doveadm obox user delete –u testuser003
</nowiki>

== doveadm sieve ==

Commands related to handling Sieve scripts.

=== doveadm sieve list ===

list user sieve scripts

parameters:

<nowiki>
{
"command": "sieveList",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve get ===

get user sieve script

parameters:

<nowiki>
{
"command": "sieveGet",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "scriptname",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve put ===

inject sieve script to user

parameters:

<nowiki>
{
"command": "sievePut",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "activate",
"type": "boolean"
},
{
"name": "scriptname",
"type": "string"
},
{
"name": "file",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve delete ===

delete user sieve

parameters:

<nowiki>
{
"command": "sieveDelete",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "ignoreActive",
"type": "boolean"
},
{
"name": "scriptname",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve activate ===

activate user sieve script

parameters:

<nowiki>
{
"command": "sieveActivate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "scriptname",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve deactivate ===

deactivate user sieve

parameters:

<nowiki>
{
"command": "sieveDeactivate",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm sieve rename ===

rename user sieve script

parameters:

<nowiki>
{
"command": "sieveRename",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "oldname",
"type": "string"
},
{
"name": "newname",
"type": "string"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

== doveadm fts ==
Dovecot fts indexing commands.

=== doveadm fts lookup ===

query user fts indexed data

parameters:

<nowiki>
{
"command": "ftsLookup",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts expand ===

<nowiki>
{
"command": "ftsExpand",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "query",
"type": "array"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts tokenize ===

<nowiki>
{
"command": "ftsTokenize",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "language",
"type": "string"
},
{
"name": "text",
"type": "array"
}
]
}
</nowiki>

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts optimize ===

<nowiki>
{
"command": "ftsOptimize",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>
{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}

=== doveadm fts rescan ===

<nowiki>
{
"command": "ftsRescan",
"parameters": [
{
"name": "allUsers",
"type": "boolean"
},
{
"name": "socketPath",
"type": "string"
},
{
"name": "user",
"type": "string"
},
{
"name": "userFile",
"type": "string"
},
{
"name": "namespace",
"type": "string"
}
]
}
</nowiki>

parameters:

{| class="wikitable"
|-
!style="font-weight: bold" |Parameter
!style="font-weight: bold" |Type
!style="font-weight: bold" |Description
!style="font-weight: bold" |example
|-
|socketPath
|String
|Path to doveadm socket
|/var/run/dovecot/doveadm-server
|-
|
|
|
|
|-
|
|
|
|
|-
|
|
|
|
|}