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.

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

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

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.

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.

$ 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

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.

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.