Rebuild Dovecot Attachment Status with doveadm

You will rebuild Dovecot's attachment-presence indicator for messages selected by a search query, then confirm which messages were processed. The examples use dovecot-core 2.3.21+dfsg1-2ubuntu6.5 installed on this machine, whose manual page documents Dovecot 2.3 behaviour.

Allow about ten minutes for a small mailbox and longer for a broad query. You need a shell, Dovecot running, and permission to use the Dovecot administration socket. This command changes mailbox metadata. It does not move or delete messages, but a broad run can touch a large number of messages and consume storage and I/O.

1. Confirm the installed command

Check the package and command before choosing a scope. These checks are ordinary and read-only:

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

The exact help output can include the global usage line and an error from a local socket when Dovecot is not available. The useful checkpoint is that the installed command lists rebuild attachments. The package version shown above is local to this host; check yours rather than assuming that a later Dovecot release has the same global options.

2. Understand what will change

doveadm rebuild attachments resets the attachment indicator for messages matching a search query and prints the UID of each match. It is an administrative, state-changing command, so do not begin with -A on a production system merely to see whether it works.

There is no documented undo operation for this rebuild. The safe recovery is to stop the command, check the scope, and rerun it with the intended query. The message contents and mailbox locations are not the target of this command, but you should still schedule a large run for a quiet period and watch the service and storage metrics.

For a first run, select one user and a narrow query. Replace the example username and subject with values from your mailbox:

$ doveadm rebuild attachments -u USERNAME SUBJECT "EXACT SUBJECT TEXT"
17
42

In this example, UIDs 17 and 42 were the matching messages. Your output will differ. A blank result can be a successful run with no matching messages, so check the exit status immediately afterwards:

$ printf 'exit status: %s\n' "$?"
exit status: 0

Do not insert another command between doveadm and the status check. A zero status confirms that the command completed, not that the query matched a message.

3. Use a known query before widening it

The shortest valid search query is ALL. It selects every message in the chosen user's mailboxes, so it is useful for a deliberate mailbox-wide rebuild but is too broad for an initial test:

$ doveadm rebuild attachments -u USERNAME ALL
1
2
3
4

Queries can combine keys, and the default operator is AND. For example, this selects messages in the Trash mailbox that are older than the supplied date:

$ doveadm rebuild attachments -u USERNAME MAILBOX Trash BEFORE 2026-01-01
23
24

Search keys are case-insensitive. Quote values that contain spaces, such as mailbox names or subjects. Treat the query as a separate review point: confirm the username, mailbox and date before pressing Enter. The search-query manual documents other keys such as FROM, SUBJECT, SEEN, LARGER and NOT.

4. Choose the user scope explicitly

With no user option, the manual says the command runs in the environment of the currently logged-in system user. That is not the same as selecting every Dovecot account. For an administrator, make the intended scope visible in the command line.

Use -u for one user or a wildcard mask. Quote a wildcard so that the shell does not expand it against local file names:

$ doveadm rebuild attachments -u 'USER*@example.org' SUBJECT "invoice"
[email protected] 8
[email protected] 31

When -u uses a wildcard, output includes both the username and UID. Verify that the account names are the ones you intended before treating the run as complete.

Use -F when you have an explicit, reviewed file containing one username per line:

$ sudo install -m 600 /dev/null /tmp/dovecot-users.txt
$ sudo sh -c 'printf "%s\n" [email protected] [email protected] > /tmp/dovecot-users.txt'
$ sudo doveadm rebuild attachments -F /tmp/dovecot-users.txt SUBJECT "invoice"
[email protected] 8
[email protected] 31

Read the file before running it:

$ sudo sed -n '1,20p' /tmp/dovecot-users.txt

These file-management commands need elevated privileges only because the example deliberately places the list in a root-owned temporary path. A normal user-owned file can be used without sudo. Remove the temporary list after checking the run if it contains sensitive account data:

$ sudo rm -- /tmp/dovecot-users.txt

5. Run all users only after reviewing the user database

-A performs the command for all users returned by the user database iteration. This is a potentially expensive, service-impacting operation. Check the configured iteration behaviour first, and confirm that the result includes only real mail users:

$ sudo doveconf -n | sed -n '/^userdb/,/^}/p'
$ sudo doveadm rebuild attachments -A SUBJECT "invoice"
[email protected] 8
[email protected] 31

The manual specifically warns about userdb { driver = passwd }: iteration can include system users below first_valid_uid. For SQL user databases, check that iterate_query matches the database layout. For LDAP, check iterate_attrs and iterate_filter. If those settings are not correct, use a reviewed -F file instead of trusting -A.

6. Add diagnostics without changing the selection

Use -v when you need a progress counter and -D when you need debug messages. Keep the same user scope and search query while diagnosing a problem:

$ sudo doveadm -v rebuild attachments -u USERNAME SUBJECT "EXACT SUBJECT TEXT"
17
42

The default output formatter is flow without a key prefix. You can request table, tab or pager with -f, but the plain default is usually easiest to capture and audit. If a remote administration socket is intentionally configured, -S accepts either an absolute UNIX socket path or a hostname:port endpoint:

$ sudo doveadm -S /var/run/dovecot/doveadm-server rebuild attachments -u USERNAME ALL

Do not invent a socket path. Check the Dovecot configuration and its permissions first. A socket error is an access or service problem, not a reason to widen the command or retry against an arbitrary endpoint.