Add, Remove and Replace Dovecot Flags with doveadm flags

You need to mark a Dovecot message as flagged, or clear a stuck keyword, and doveadm flags does it from the shell. This guide takes about ten minutes for a single message, longer if you need to review a broad search first.

You will change the flags or keywords on selected messages, then verify the result without touching unrelated mail. The examples use doveadm flags from dovecot-core version 1:2.3.21+dfsg1-2ubuntu6.5 on this machine.

You need: a working Dovecot installation, a mailbox name, a target user's name, and a message you can identify safely.
Privileges: these are administrative mailbox operations. They normally need Dovecot administration access, but not sudo when your account is already authorised to run doveadm. Use elevated privileges only under your normal server policy.

1. Confirm the installed command and inspect the target

Start with read-only checks. The installed manual page documents Dovecot 2.3 syntax, and the package query records the exact distribution build:

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

Before changing anything, fetch the UID and current flags for one known message. Replace every uppercase placeholder with a value from your server:

$ doveadm fetch -u USER 'uid flags' mailbox MAILBOX uid UID
uid: UID
flags: \Seen ExistingKeyword

The output is host-specific. Record the current flags, because that record is your simplest recovery plan if you need to undo a change.

Checkpoint: Do not continue until the user, mailbox and UID identify the message you intended. A UID is scoped to its mailbox, so the same number in another mailbox can be a different message.

2. Choose the narrowest search query

The final arguments are a search query. Multiple search keys are combined with AND by default, so include the mailbox and a precise UID when working on one message:

mailbox INBOX uid 81563

Other useful keys include SEEN, FLAGGED, FROM, SUBJECT, BEFORE, SINCE and KEYWORD. For example, this describes messages in one mailbox that are both seen and flagged:

mailbox INBOX SEEN FLAGGED

Test a wider query with doveadm search first. It prints matching mailbox and UID information without changing flags:

$ doveadm search -u USER mailbox INBOX SEEN FLAGGED
INBOX 81563
INBOX 81570

Warning: Do not skip this check before using -A, -F, a wildcard user mask, or a query such as ALL. A syntactically valid query can still match far more mail than you meant to change.

3. Add a flag or keyword

Use flags add when the existing flags must stay and you want to extend them. Standard IMAP flags include \Seen, \Answered, \Flagged, \Draft, \Deleted and \Recent. Dovecot also accepts IMAP keywords and user-defined keywords.

$ doveadm flags add -u USER '\Flagged $Forwarded' mailbox INBOX uid 81563

Quote the flags as one shell argument. The backslash in \Flagged and the dollar sign in $Forwarded must reach doveadm unchanged. The command normally prints no success message, so verify the new state:

$ doveadm fetch -u USER 'uid flags' mailbox INBOX uid 81563
uid: 81563
flags: \Seen \Flagged $Forwarded

Recovery: Adding a flag is generally easy to undo. Run flags remove with the same flag and the same search query.

4. Remove a flag or keyword

Use flags remove to delete only the named flags from matching messages. Other flags stay in place:

$ doveadm flags remove -u USER '$Forwarded' mailbox INBOX uid 81563
$ doveadm fetch -u USER 'uid flags' mailbox INBOX uid 81563
uid: 81563
flags: \Seen \Flagged

Removing \Deleted can make a message appear undeleted, but that is not the same as recovering a message already expunged from storage. Flags are not a backup mechanism. Keep the original fetch output until you have confirmed the desired state.

Recovery: If you removed a flag by mistake, add that exact flag again. If you do not know what was present before the command, stop and inspect your logs or audit record rather than guessing.

5. Replace every flag only with a recorded plan

flags replace is different from add and remove: it replaces all current flags on every matching message with the supplied set. That can discard useful state, including \Seen, \Answered and user-defined keywords.

Warning: Treat flags replace as destructive and review the match set before running it.

$ doveadm search -u USER mailbox INBOX uid 81563
INBOX 81563
$ doveadm fetch -u USER 'uid flags' mailbox INBOX uid 81563
uid: 81563
flags: \Seen OldLabel
$ doveadm flags replace -u USER '\Flagged NewLabel' mailbox INBOX uid 81563

Verify that only the planned set remains:

$ doveadm fetch -u USER 'uid flags' mailbox INBOX uid 81563
uid: 81563
flags: \Flagged NewLabel

There is no automatic undo command. Restore the previous set explicitly, using the flags you recorded before replacement:

$ doveadm flags replace -u USER '\Seen OldLabel' mailbox INBOX uid 81563

Recovery: If the old state was not recorded, do not invent a replacement. Mail-client state may have changed independently, and a guessed restore can overwrite more information.

6. Limit administrative scope

With -u USER, the command targets one user. The option also accepts * and ? wildcards, so quote a mask when the shell might expand it:

$ doveadm flags add -u '*@example.org' '\Flagged' mailbox INBOX SUBJECT 'needs review'

-A means all users. It applies the command to all users found through the user database.
-F FILE means a list. It reads one username per line and applies the command to those users.
Both are broad. With SQL or LDAP user databases, iteration settings must describe the complete user set or some users may be missed. With a passwd user database, -A can include system users below Dovecot's first_valid_uid boundary, which the manual specifically warns against.

Tip: If you omit -u, -A and -F, doveadm uses the environment of the currently logged-in user. That default is easy to miss when copying a command between an administrator shell and a service account. State the user explicitly in scripts and runbooks.

7. Diagnose a failed or surprising operation

First rerun the read-only search or fetch command with the exact user, mailbox and query. Check shell quoting, especially around backslashes, dollar signs, wildcard masks and parentheses. If a query combines OR with other terms, follow the search-query syntax and quote parentheses for the shell.

If the command cannot connect to the expected administration endpoint, -S can select an absolute UNIX socket path or a remote hostname:port. Use the socket supplied by your Dovecot configuration or administrator. Do not guess a remote endpoint or send mailbox-changing commands across an untrusted network.

A successful exit status means the command completed its request. It does not prove the query matched the messages you intended. The post-change fetch is the real verification, and a second search can confirm the scope after a broad operation.

Done means

Versions checked. The installed doveadm and dovecot-core versions are recorded.
Target inspected. You looked at the set with search or fetch before changing state.
Right verb used. flags add preserved existing flags, and flags remove undid a known addition.
Replace was planned. flags replace ran only after you recorded the old flags and reviewed every match.
Result compared. The final flags were fetched and match the intended result.
Scope kept small. Broad user selection and elevated access were treated as administrative changes, not defaults to copy blindly.