Manage Dovecot Mailboxes Safely with doveadm

Delete the wrong folder with doveadm mailbox and the messages in it are gone, no Trash, no undo. This guide covers listing a user's folders, checking message counts, creating or renaming a mailbox, and removing one only after checking the target. Allow about 15 minutes for a read-only inspection, longer if you're planning a change. It 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 don't need sudo when your account already has the required access. Adding sudo doesn't fix a wrong user database, namespace or socket path.

1. Confirm the command and choose one user

Start with a read-only help check and pin down the account whose mailboxes you're inspecting:

$ 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 point at the wrong population, so don't start there. Omit all three selectors and doveadm uses the currently logged-in user's own environment, a surprising default in an administrator shell.

2. List folders and subscriptions

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

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

Your own names will differ. The -s form shows subscriptions, and those entries can include subscriptions to a mailbox that's already been deleted. Mailbox names appear as IMAP clients see them, but the hierarchy separator depends on storage and namespace configuration: don't assume / is always it.

For international names, pick the encoding explicitly. -8 converts UTF-8 input to modified UTF-7; -7 converts modified UTF-7 back to UTF-8. mailbox mutf7 defaults to -8:

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

Treat that output as a name conversion, not a mailbox existence test: the command doesn't create or rename anything.

3. Inspect status before you change anything

Ask for a small set of fields first. status 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 ones: messages, recent, unseen, vsize, uidnext, uidvalidity, highestmodseq, guid. unseen here is the sequence number of the first unseen message, not a count.

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 get summarised. Check the target and the counts before anything destructive.

4. Create, subscribe or rename a mailbox

Creating a mailbox is a state change, but normally a reversible one. 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 physical format comes from mail_location or the user's mail field. Don't try to pick a storage format by changing the mailbox name.

Rename only after confirming both names and any client or delivery rule that references the old one:

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

Use -s on the rename to drop the old subscription and subscribe the new name. To undo this example, rename Projects/2027 back to Projects/2026, then check 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 isn't what you expect. Need a whole tree gone? Inspect every child first, then use -r. Avoid -Z unless you're deleting an entire user and accept its warning: it's faster but can leave the user briefly inconsistent, for example with wrong quota data. There's no mailbox-delete undo; 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 outside migration or disaster recovery, and not every backend supports it. Don't use it to fix an ordinary display or subscription glitch. Cache purge and cache-decision commands are maintenance operations too, not routine mailbox management.

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