.\" Copyright (c) 2013-2018 Dovecot authors, see the included COPYING file
.TH DOVEADM\-FLAGS 1 "2015-05-09" "Dovecot v2.3" "Dovecot"
.SH NAME
doveadm\-flags \- add, remove or replace messages\(aq flags
.\"------------------------------------------------------------------------
.SH SYNOPSIS
.BR doveadm " [" \-Dv "] " flags " [" \-S
.IR socket_path "] " "command flags search_query"
.\"-------------------------------------
.br
.BR doveadm " [" \-Dv "] " flags " [" \-S
.IR socket_path "] " "command flags search_query"
.B \-A
.\"-------------------------------------
.br
.BR doveadm " [" \-Dv "] " flags " [" \-S
.IR socket_path "] " "command flags search_query"
.BI "\-F " file
.\"-------------------------------------
.br
.BR doveadm " [" \-Dv "] " flags " [" \-S
.IR socket_path "] " "command flags search_query"
.BI "\-u " user
.\"------------------------------------------------------------------------
.SH DESCRIPTION
This command is used to manipulate flags of messages.
.\"------------------------------------------------------------------------
.SH OPTIONS
Global
.BR doveadm (1)
.IR options :
.TP
.B \-D
Enables verbosity and debug messages.
.TP
.BI \-o\  setting = value
Overrides the configuration
.I setting
from
.I /etc/dovecot/dovecot.conf
and from the userdb with the given
.IR value .
In order to override multiple settings, the
.B \-o
option may be specified multiple times.
.TP
.B \-v
Enables verbosity, including progress counter.
.\"-------------------------------------
.PP
Command specific
.IR options :
.\"-------------------------------------
.TP
.B \-A
If the
.B \-A
option is present, the
.I command
will be performed for all users.
Using this option in combination with system users from
.B userdb { driver = passwd }
is not recommended, because it contains also users with a lower UID than
the one configured with the
.I first_valid_uid
setting.
.sp
When the SQL userdb module is used make sure that the
.I iterate_query
setting in
.I /etc/dovecot/dovecot\-sql.conf.ext
matches your database layout.
When using the LDAP userdb module, make sure that the
.IR iterate_attrs " and " iterate_filter
settings in
.I /etc/dovecot/dovecot-ldap.conf.ext
match your LDAP schema.
Otherwise
.BR doveadm (1)
will be unable to iterate over all users.
.\"-------------------------------------
.TP
.BI \-F\  file
Execute the
.I command
for all the users in the
.IR file .
This is similar to the
.B \-A
option,
but instead of getting the list of users from the userdb,
they are read from the given
.IR file .
The
.I file
contains one username per line.
.\"-------------------------------------
.TP
.BI \-S\  socket_path
The option\(aqs argument is either an absolute path to a local UNIX domain
socket, or a hostname and port
.RI ( hostname : port ),
in order to connect a remote host via a TCP socket.
.sp
This allows an administrator to execute
.BR doveadm (1)
mail commands through the given socket.
.\"-------------------------------------
.TP
.BI \-u\  user/mask
Run the
.I command
only for the given
.IR user .
It\(aqs also possible to use
.RB \(aq * \(aq
and
.RB \(aq ? \(aq
wildcards (e.g. \-u *@example.org).
.br
When neither the
.B \-A
option, nor the
.BI \-F\  file
option, nor the
.BI \-u\  user
was specified, the
.I command
will be executed with the environment of the
currently logged in user.
.\"------------------------------------------------------------------------
.SH ARGUMENTS
.TP
.I flags
Message flags as described in RFC 3501, section 2.3.2 (Flags Message
Attribute):
.BR \(rsAnswered ", " \(rsDeleted ", " \(rsDraft ", " \(rsFlagged ", "
.BR \(rsRecent " and " \(rsSeen .
And the IMAP keywords
.BR \(DoForwarded ", " \(DoMDNSent ", " \(DoSubmitPending " and "
.B \(DoSubmitted
or user\-defined keywords, e.g. Junk, \(DoNonSpam or \(DoLabel1.
.br
One or multiple flags and/or keywords can be specified.
.\"-------------------------------------
.TP
.I search_query
Manipulate the flags of messages matching the given search query.
See
.BR doveadm\-search\-query (7)
for details.
.\"------------------------------------------------------------------------
.SH COMMANDS
.SS flags add
.BR "doveadm flags add" " [" \-u
.IR user |\c
.BR \-A | \-F
.IR file ]
.RB [ \-S
.IR socket_path "] " "flags search_query"
.PP
This command is used to extend the current set of flags with the given
.IR flags .
.\"-------------------------------------
.SS flags remove
.BR "doveadm flags remove" " [" \-u
.IR user |\c
.BR \-A | \-F
.IR file ]
.RB [ \-S
.IR socket_path "] " "flags search_query"
.PP
In order to remove the given
.I flags
from the current set of flags, use this command.
.\"-------------------------------------
.SS flags replace
.BR "doveadm flags replace" " [" \-u
.IR user |\c
.BR \-A | \-F
.IR file ]
.RB [ \-S
.IR socket_path "] " "flags search_query"
.PP
This command is used to replace ALL current flags with the given
.IR flags .
.\"------------------------------------------------------------------------
.SH EXAMPLE
List and manipulate the message flags of the message with uid 81563
.sp
.nf
.ft B
doveadm fetch \-u bob \(aquid flags\(aq mailbox dovecot uid 81563
.ft P
uid: 81563
flags: \(rsAnswered \(rsSeen NonJunk

.ft B
doveadm flags remove \-u bob NonJunk mailbox dovecot uid 81563
doveadm flags add \-u bob \(aq\(rsFlagged \(DoForwarded\(aq \
mailbox dovecot uid 81563
.ft P
.fi
.\"------------------------------------------------------------------------
.SH REPORTING BUGS
Report bugs, including
.I doveconf \-n
output, to the Dovecot Mailing List <dovecot@dovecot.org>.
Information about reporting bugs is available at:
http://dovecot.org/bugreport.html
.\"------------------------------------------------------------------------
.SH SEE ALSO
.BR doveadm (1),
.BR doveadm\-fetch (1),
.BR doveadm\-search\-query (7)