Safely Reclaim Unreferenced mdbox Messages with doveadm purge

You will finish with a controlled way to remove messages whose mdbox reference count is zero, first for one mailbox account and then, if justified, for a reviewed set of users. The examples use the installed Dovecot 2.3 command from dovecot-core package version 1:2.3.21+dfsg1-2ubuntu6.5.

Allow about fifteen minutes for a single-user check, plus whatever maintenance window your storage needs. You need access to the Dovecot host, a working doveadm configuration and an account whose mail storage uses mdbox. The command changes mail storage, so take a backup or snapshot according to your retention policy before a broad run. There is no undo option in doveadm purge.

1. Confirm the installed command

Start with the read-only checks. These do not purge anything and normally need no sudo:

$ command -v doveadm
/usr/bin/doveadm
$ dpkg-query -W -f='${Package} ${Version}\n' dovecot-core
dovecot-core 1:2.3.21+dfsg1-2ubuntu6.5
$ doveadm help purge
DOVEADM-PURGE(1)                    Dovecot                   DOVEADM-PURGE(1)

NAME
       doveadm-purge - Remove messages with refcount=0 from mdbox files

The installed manual defines four target forms: the current user, every user, users read from a file, or a user mask. It also confirms that -v enables progress output and -D enables debug messages.

2. Understand what purge removes

mdbox stores a message once and tracks how many mailbox instances still refer to it. Expunging the last instance lowers that reference count to zero. doveadm purge removes those no-longer-referenced messages from the mdbox files. It is storage cleanup after deletion, not a replacement for doveadm expunge.

This distinction matters. If a message is still present in a mailbox, purge should not remove it merely because it is old. Conversely, a message that has been expunged everywhere is already logically deleted and will not be recoverable through normal mailbox operations after its storage is reclaimed.

The command is therefore destructive even though it does not select messages by date or search query. It acts on the storage belonging to the users you select. Do not run a broad target until you have checked the user database iteration and retained a usable backup.

3. Test one explicit user

Choose an exact mailbox account and record it before running the command. Replace the example value with a real account from your deployment:

$ MAIL_USER='[email protected]'
$ doveadm purge -u "$MAIL_USER"
$ printf 'exit status: %s\n' "$?"
exit status: 0

This is an administrative mail operation and may require the Dovecot administrator's privileges, depending on the local socket and configuration. Use sudo only when the normal administrator invocation requires it, for example sudo doveadm purge -u "$MAIL_USER". Do not put a password, token or other secret into the command line.

A zero status means the selected operation completed successfully. It does not promise that a particular number of bytes was reclaimed. Some users may have no refcount-zero messages, and the command's normal output can be empty. With progress enabled, ask for more visibility:

$ doveadm -v purge -u "$MAIL_USER"
$ printf 'exit status: %s\n' "$?"
exit status: 0

Run the verbose form during your test, not an unbounded all-user job. Save the output and timestamp with the maintenance record.

4. Review a fixed user list

Use -F when you have a deliberately reviewed list rather than trusting user database iteration. The file contains one username per line:

$ install -m 600 /dev/null /tmp/doveadm-purge-users.txt
$ editor /tmp/doveadm-purge-users.txt
$ sed -n '1,20p' /tmp/doveadm-purge-users.txt
[email protected]
[email protected]
$ doveadm -v purge -F /tmp/doveadm-purge-users.txt
$ printf 'exit status: %s\n' "$?"
exit status: 0

The file is input data, not a shell script. Keep one complete username on each line and remove blank or accidental entries before execution. Check the list against your backup scope and maintenance ticket. The command reads the usernames itself, so shell quoting inside the file has no special meaning.

Recovery checkpoint: if the list is wrong, stop before the purge command. After it has run, remove the temporary list with rm -- /tmp/doveadm-purge-users.txt only when you no longer need the audit copy. Deleting the list does not restore purged messages.

5. Use all-user mode only after checking iteration

-A asks Dovecot to run the operation for every user returned by the user database. Before using it, inspect the effective configuration:

$ doveconf -n | less
$ doveconf -n | rg -n 'userdb|iterate_query|iterate_attrs|iterate_filter|first_valid_uid'

For SQL user databases, the manual specifically requires an iterate_query that matches the database layout. For LDAP, check iterate_attrs and iterate_filter against the directory schema. With the passwd user database, the manual warns that -A can include system users below first_valid_uid. If iteration is incomplete or too broad, use a reviewed -F file instead.

Only after those checks, and with a current recovery point, run:

$ sudo doveadm -v purge -A
$ printf 'exit status: %s\n' "$?"
exit status: 0

Expect the job to take longer than the single-user test. Avoid overlapping it with mailbox migrations, storage maintenance or other jobs that heavily access the same mail files.

6. Troubleshoot scope and connection errors

A missing or mistyped user target is a scope problem. Recheck the exact account, the list file and the user database before adding privileges. A successful sudo does not make a non-existent mailbox appear.

When the administrator command must use another doveadm socket, pass an absolute local socket path or a remote hostname:port value with -S:

$ sudo doveadm -S /run/dovecot/doveadm-server purge -u "$MAIL_USER"

Use the socket path documented by your Dovecot configuration. Do not guess a remote endpoint, and treat TCP access as security-sensitive. If you need diagnostics, add -D, but review its output before sharing it because debug logs can expose deployment details.

If you need to override a configuration setting for a controlled test, -o setting=value can be repeated. Do not use it to bypass authentication, redirect mail storage or change a production setting without a documented rollback. The ordinary recovery path for a failed purge is to stop the job, preserve the error output, and restore the affected mail storage from the tested backup or snapshot if required.