Restore Selected Mail Safely with doveadm import

Someone deleted the wrong folder, and all you have is a Maildir or mdbox backup: doveadm import pulls selected messages back into a user's mailbox. You will run one narrow, checkable import instead of a blind bulk copy. Allow about fifteen minutes for a small test, longer for a real mailbox.

The examples target the installed Dovecot 2.3.21 package, dovecot-core 1:2.3.21+dfsg1-2ubuntu6.5.

• What you need: a readable source mailbox, a configured Dovecot destination, and an account permitted to run doveadm mail commands.
• What it is: a restore or merge, not a transport migration. It writes mail and can create mailboxes.
• Privileges: the command normally needs elevated privileges or an account with suitable Dovecot access. The inspection commands below do not.

Treat the source path, destination user and search query as a change plan.

1. Check the installed command

Start with a read-only version and syntax check. The installed manpage is the contract for this host, so do not copy options from a different Dovecot release without checking them:

$ doveadm --version
2.3.21
$ man doveadm-import

The command takes three positional arguments:

• source_location uses the same style as Dovecot's mail_location setting, such as maildir:/backup/user/Maildir or mdbox:/backup/user/mdbox.
• dest_parent is the parent mailbox the imported folders land under.
• search_query selects which messages to import.

2. Make a narrow test plan

Choose the destination with -u. While testing, put a non-empty parent mailbox such as Restore-2026-09 around the imported folders. Dovecot creates that parent if it does not exist:

$ doveadm import -u '[email protected]' \
    'maildir:/srv/backup/jane.doe/Maildir' \
    'Restore-2026-09' \
    'mailbox INBOX from [email protected]'

This imports messages in the source INBOX whose sender matches [email protected]. Quote the query as one shell argument when it contains spaces. It is a Dovecot search query, so use the search-query documentation for operators rather than guessing at shell syntax.

For a complete backup, use all as the query:

$ doveadm import -u '[email protected]' \
    'mdbox:/srv/backup/jane.doe/mdbox' \
    'Restore-2026-09' \
    all

3. Decide which user opens the source

By default the source is opened in the destination user's context. If the source belongs to another Dovecot user and your access model permits it, add -U:

# Run with the Dovecot administrator account or suitable privilege.
$ doveadm import -U '[email protected]' \
    -u '[email protected]' \
    'maildir:/srv/mail/backup-owner/Maildir' \
    'Restore-2026-09' \
    'mailbox INBOX all

-U changes the username used to open the source. It does not change the destination chosen by -u. Check filesystem permissions and Dovecot's user database before running this form.

4. Run one controlled import

Use -v for a progress counter. Add -s only if the destination parent and newly created mailboxes should be subscribed:

# Elevated operation: this creates mailboxes and copies messages.
$ doveadm -v import -u '[email protected]' -s \
    'maildir:/srv/backup/jane.doe/Maildir' \
    'Restore-2026-09' \
    'mailbox INBOX from [email protected]'
import: copied messages

Progress text varies with the mailbox and installed build. The useful success signal is an exit status of zero, followed by a check of the destination through IMAP or a read-only doveadm command such as:

$ printf 'exit status: %s\n' "$?"
exit status: 0
$ doveadm search -u '[email protected]' mailbox 'Restore-2026-09/INBOX' ALL

5. Scale to a user list only after verification

For several known users, put one username per line in a file and use -F. Creating that file is an ordinary local shell action, but review it before the import:

$ sed -n '1,20p' /root/restore-users.txt
[email protected]
[email protected]
$ doveadm -v import -F /root/restore-users.txt \
    'maildir:/srv/backup/common/Maildir' \
    'Restore-2026-09' \
    'mailbox INBOX from [email protected]'

-A gets users from the configured user database instead. Use it only when iteration is known to work:

• SQL needs a matching iterate_query.
• LDAP needs matching iteration settings.
• passwd user databases can include system users below first_valid_uid, as the manpage warns.

For a controlled recovery, -F is usually easier to audit than -A.

6. Handle duplicates and undo carefully