Home / Alt manpages / doveadm-search(1)

  • doveadm-search(1)
  • User command
  • linux

Find Messages and Reuse UIDs with doveadm search

Somewhere in a mailbox sits the one message you need, and doveadm search turns "somewhere" into a mailbox GUID and UID you can act on. You will run a query, read the GUID and UID pairs it returns, and pass them 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.

The route

Jump straight to the step you need, or tick off Done means at the end.

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

Global options come before search. For example, put -f tab before search, not after it.

The installed manual describes four useful scopes:

  • Current user. The current system user's environment.
  • Everyone. Every user, with -A.
  • A list. Users read from a file.
  • One user or mask. Chosen with -u.

Checkpoint

If doveadm --version reports a different major release, read that installation's manual before copying the examples. The local page is specifically the Dovecot v2.3 doveadm-search(1) interface.

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 is a mailbox GUID followed by a message UID. The values above are illustrative, so yours will differ. The query combines mailbox INBOX and subject invoice. The search-query manual is the reference for available 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.

Checkpoint

A successful search may print no lines when nothing matches. That is not an error. Capture the status when scripting:

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

3. Pick 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. 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 puts 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.

Tip

If you see search: invalid option -- 'f', move the formatter before the subcommand, as in doveadm -f tab search ....

4. Widen the scope on purpose

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.

Warning

The manpage says that using -A with a system-user database can include users below Dovecot's first_valid_uid. 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 earns its keep 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

Warning

This example writes message bodies into files in the current directory. That is state-changing and potentially sensitive: message content may be confidential, and an existing file with the same UID may be overwritten. Choose a protected output directory, confirm its ownership and permissions, and make sure the filename policy suits 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. Adding sudo does not fix a missing account, so check the spelling and the user database configuration first.

On a host where the Dovecot administration socket is protected, an ordinary account may also get a permission error. Use the account and socket access policy the administrator approves, 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'

Warning

Do not guess a socket or expose a TCP endpoint just to make a test pass. A remote socket is an administrative interface, so 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. They do not repair a missing user, a bad query or an unavailable socket.

Done means

  • Version confirmed. You checked the installed doveadm version and kept global options before search.
  • Narrow test run. You searched a named user with a narrow mailbox and subject query.
  • Pairs readable. You can read the returned mailbox GUID and message UID pair.
  • Scope understood. You know when -A, -F and wildcard -u broaden the search.
  • Formatter chosen. You can pick one without mistaking a human-readable table for a processing stream.
  • Chaining checked. You reviewed permissions and output handling before feeding results to a command that reads or writes message content.