Manage Dovecot Mailboxes Safely with doveadm

You will use doveadm mailbox to list a user's folders, inspect message counts, create or rename a mailbox, and remove one only after checking the target. Allow about 15 minutes for a read-only inspection, or longer if you need to plan a change. This guide follows the installed Dovecot 2.3.21 package, dovecot-core 1:2.3.21+dfsg1-2ubuntu6.5. The local manual is labelled Dovecot v2.3, so treat that installed interface as the contract.

You need a shell and a Dovecot administration account with access to the relevant doveadm socket. Most examples are administrator operations, but they do not need sudo when your account already has the required access. Adding sudo does not repair a wrong user database, namespace or socket path.

1. Confirm the command and choose one user

Start with a read-only help check and identify the account whose mailboxes you intend to inspect:

$ command -v doveadm
/usr/bin/doveadm
$ doveadm help mailbox
... mailbox      cache|create|delete|list|metadata|mutf7|path|rename|status|subscribe|unsubscribe|update

Use -u USER for a single user. The manual also supports -A for all users and -F FILE for one username per line. Those wider selectors are easy to apply to the wrong population, so do not begin with them. If you omit all three selectors, doveadm uses the currently logged-in user's environment, which is a surprising default for an administrator shell.

2. List folders and subscriptions

List the mailboxes visible to the selected user. A mailbox mask may contain wildcards:

$ doveadm mailbox list -u '[email protected]' '*'
INBOX
Sent
Archive/2025
$ doveadm mailbox list -s -u '[email protected]' '*'
INBOX
Sent

Your names will differ. The -s form shows subscriptions, and those entries can include subscriptions whose mailbox has already been deleted. Mailbox names are presented as IMAP clients see them, but the hierarchy separator depends on the storage and namespace configuration. Do not assume that / is always the separator.

For international names, choose the encoding explicitly. -8 converts UTF-8 input to modified UTF-7, while -7 converts modified UTF-7 input to UTF-8. The default for mailbox mutf7 is -8:

$ doveadm mailbox mutf7 -8 'Archive/台北'
Archive/&U,BTFw-/

Use the output as a name conversion, not as a mailbox existence test. The command does not create or rename anything.

3. Inspect status before changing anything

Ask for a small set of fields first. The status command uses the flow formatter by default:

$ doveadm mailbox status -u '[email protected]' 'messages vsize unseen' INBOX
messages=42 vsize=187654 unseen=3

Quote multiple fields as one argument. Useful fields include messages, recent, unseen, vsize, uidnext, uidvalidity, highestmodseq and guid. The unseen value is the message sequence number of the first unseen message, not a count of unseen messages.

For output intended for a report, use a table:

$ doveadm -f table mailbox status -u '[email protected]' 'messages vsize' 'Archive*'
mailbox             messages vsize
Archive/2025        12       54321

With -t, values for messages, recent, unseen and vsize across multiple mailboxes are summarised. Check the target and the counts before a destructive command.

4. Create, subscribe or rename a mailbox

Creating a mailbox is a state change, but it is normally reversible. Add -s if the new folder should also be subscribed:

$ doveadm mailbox create -u '[email protected]' -s 'Projects/2026'
$ doveadm mailbox list -s -u '[email protected]' 'Projects*'
Projects/2026

The mailbox's physical format comes from mail_location or the user's mail field. Do not try to select a storage format by changing the mailbox name.

Rename only after confirming both names and any client or delivery rules that refer to the old name:

$ doveadm mailbox rename -u '[email protected]' 'Projects/2026' 'Projects/2027'
$ doveadm mailbox list -u '[email protected]' 'Projects*'
Projects/2027

Use -s on the rename if the old subscription should be removed and the new name subscribed. To undo this example, rename Projects/2027 back to Projects/2026, then verify subscriptions separately.

5. Treat deletion as irreversible

$ doveadm mailbox status -u '[email protected]' 'messages' 'Projects/2026'
$ doveadm mailbox delete -u '[email protected]' -e 'Projects/2026'
$ doveadm mailbox list -u '[email protected]' 'Projects*'

Stop if the status is not what you expect. If you deliberately need a tree, inspect every child, then use -r. Avoid -Z unless you are deleting an entire user and have accepted its warning: it is faster but can leave the user temporarily inconsistent, for example with incorrect quota data. There is no mailbox-delete undo command; recover from your mail backup or restore procedure.

6. Keep migration-only commands separate

mailbox update changes UID validity, next UID, recent UID and modification sequence values. The manual strongly discourages it except during migration or disaster recovery, and not all backends support it. Do not use it to correct an ordinary display or subscription problem. Likewise, cache purge and cache-decision commands are maintenance operations, not routine mailbox management.

When a command fails, preserve the error text and first recheck the user, mailbox spelling, namespace separator and socket access. A test with a deliberately nonexistent account should fail with a user lookup error, not silently select another account. Keep -A, -F and remote -S changes out of an incident response until the single-user command works.