Search Dovecot Mailboxes and Reuse the Matching UIDs

You will finish with a repeatable way to ask Dovecot which messages match a search query, read the returned mailbox GUID and message UID pairs, and pass those pairs to a follow-up command. The examples target the installed Dovecot 2.3.21 command from package dovecot-core version 1:2.3.21+dfsg1-2ubuntu6.5.

Allow about fifteen minutes. You need a shell, a configured Dovecot installation, and permission to run doveadm for the mailbox scope you choose. This guide only searches and reads identifiers. It does not delete, move, flag or export messages.

1. Check the installed command

Confirm which executable will run and record its version. These are ordinary, read-only commands:

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

The command's global options come before search. For example, put -f tab before search, not after it. The installed manual describes four useful scopes: the current system user's environment, every user, users read from a file, or one user or mask.

2. Search one user's mailboxes first

Start with a named account and a narrow query. Replace USER_NAME with an account that exists in this Dovecot installation:

$ USER_NAME='[email protected]'
$ doveadm search -u "$USER_NAME" mailbox INBOX subject 'invoice'
3a94c928d66ebe4bda04000015811c6a  8
3a94c928d66ebe4bda04000015811c6a  25

Each result line contains a mailbox GUID followed by a message UID. The values above are illustrative, so your GUIDs and UIDs will differ. The query combines mailbox INBOX and subject invoice; the search-query manual is the reference for available search keys and their arguments.

Mailbox names can use Dovecot's wildcard syntax. The installed manpage demonstrates an escaped asterisk when matching a mailbox family:

$ doveadm search -u "$USER_NAME" mailbox dovecot\* subject 'todo'

Keep the backslash or quote the wildcard according to the query syntax you intend. Do not let the shell expand an unquoted wildcard against local file names.

$ doveadm search -u "$USER_NAME" mailbox INBOX subject 'invoice'
$ status=$?
$ printf 'doveadm status: %s\n' "$status"
doveadm status: 0

3. Choose output that suits the next command

The default formatter is flow, but this command omits the usual key= prefix and prints the GUID and UID as fields on each line. Use tab when a person needs a header, or keep the default when a simple two-column stream is easier to process:

$ doveadm -f tab search -u "$USER_NAME" mailbox INBOX subject 'invoice'
mailbox-guid                           uid
3a94c928d66ebe4bda04000015811c6a      8
3a94c928d66ebe4bda04000015811c6a      25

The other documented formatters are table, which aligns columns, pager, which places each key and value on its own line and separates records with a form feed, and flow. Do not parse aligned table output as if it were a stable machine format.

4. Search several users without widening the scope by accident

For all users, use -A:

$ doveadm search -A mailbox INBOX subject 'invoice'
[email protected]  3a94c928d66ebe4bda04000015811c6a  8
[email protected]    44f68b13ce97044b837f000035ca9452  14

With -A, the output includes the username as well as the mailbox GUID and UID. This can touch every account in the configured user database. The manpage warns that using it with a system-user database can include users below Dovecot's first_valid_uid, so check the user database and iteration settings before using it on a large service.

Use -F when the intended scope is an explicit file. It must contain one username per line:

$ doveadm search -F /path/to/user-list.txt mailbox INBOX subject 'invoice'

Use -u with a wildcard when that is genuinely the requirement. The documented examples include * and ?, such as -u '*@example.org'. Quote the mask so the shell does not interpret it first. Treat -A, -F and wildcard searches as a review point: they broaden which mailboxes are inspected, even though the search itself does not modify messages.

5. Feed results to doveadm fetch

search is useful because a later command can use its identifiers. The installed manpage shows this pattern for fetching message bodies from matching messages:

$ doveadm search -u "$USER_NAME" mailbox INBOX subject 'todo' |
> while read -r guid uid; do
>   doveadm fetch -u "$USER_NAME" body mailbox-guid "$guid" uid "$uid" > "msg.$uid"
> done

This example writes message bodies into files in the current directory. That is a state-changing and potentially sensitive operation: message content may contain confidential data, and an existing file with the same UID may be overwritten. Before using it, choose a protected output directory, confirm its ownership and permissions, and make sure the filename policy is suitable for your mailbox. The search command alone does not write those files.

For a safer first check, print only the identifiers:

$ doveadm search -u "$USER_NAME" mailbox INBOX subject 'todo' |
> while read -r guid uid; do
>   printf 'mailbox-guid=%s uid=%s\n' "$guid" "$uid"
> done
mailbox-guid=3a94c928d66ebe4bda04000015811c6a uid=8

6. Diagnose the common failures

A named user must exist and be reachable through the configured user database. A missing account is not fixed by adding sudo; check the spelling and the user database configuration first. On a host where the Dovecot administration socket is protected, an ordinary account may also receive a permission error. Use the account and socket access policy approved by the administrator, then repeat the same narrow query.

For a remote Dovecot administration endpoint or a specific local UNIX socket, use -S followed by an absolute socket path or a hostname:port value:

$ doveadm -S /run/dovecot/doveadm-server search -u "$USER_NAME" mailbox INBOX subject 'invoice'

Do not guess a socket or expose a TCP endpoint simply to make a test pass. A remote socket is an administrative interface; confirm its address, transport protection and access controls before using it. The -D and -v global options add debug or progress output when an administrator needs diagnostics, but they do not repair a missing user, bad query or unavailable socket.