.\" Copyright (c) 2010-2013 Dovecot authors, see the included COPYING file
.TH DOVEADM\-EXPUNGE 1M "2013-11-24" "Dovecot v2.2" "Dovecot"
.SH NAME
doveadm expunge \- Expunge messages matching given search query
.\"------------------------------------------------------------------------
.SH SYNOPSIS
.nh
.na
.HP
\" ./global-options-short.inc
\" ./master-options-short.inc
\" ./mail-options-short.inc
\fBdoveadm expunge\fR [\-D] [\-F\ \fIformatter\fR] [\-v] [\-c\ \fIfile\fR|\-i\ \fIinstance\fR] [\-k] [\-L] [\-O] [\-o\ \fIsetting\fB=\fIvalue\fR]...  [\-S\ \fIsocket\fR] [\-A|\-u\ \fIuser\fR] [\-d] \fIsearch_query\fR
.ad
.hy
.\"------------------------------------------------------------------------
.SH DESCRIPTION
This command can be used to expunge mails matching the given search query.
It is typically used to expunge old mails from users\' Trash and/or Spam
mailboxes. To test which messages a given search query would match, you can
use
.B doveadm fetch
or
.B doveadm search
commands.
.\"------------------------------------------------------------------------
.SH OPTIONS
Common options:

\" ./global-options.inc

\" vim: ts=4 sw=4 filetype=nroff
.TP
.B \-D
Enables verbosity and debug messages.

.TP
.BI \-F\  formatter
Specifies the \fIformatter\fR for formatting the output.  Supported formatters
are:
.RS
.TP 2
.B flow
Prints each line with
.IB key = value
pairs.
.TP
.B pager
Prints each
.IB key = value
pair on its own line and separates records with form feed character (\fB^L\fR).
.TP
.B tab
Prints a table header followed by tab separated value lines.
.TP
.B table
Prints a table header followed by adjusted value lines.
.RE

.TP
.B \-v
Enables verbosity, including progress counter.
\" ./master-options.inc

\" vim: ts=4 sw=4 filetype=nroff
.TP
.BI \-c\  file
Read configuration from the given \fIfile\fR.  By default
\fI/etc/dovecot/dovecot.conf\fR will be used.

.TP
.BI \-i\  instance
Get the configuration from the instance with the name \fIinstance\fR.

.TP
.B \-k
Keep environment, i.e. when executing a new process do not explicitly set 
the environment variables HOME, USER and when reading configurations, don\'t
overwrite currently set environment variables with corresponding settings.
Usually used internally, only.

.TP
.B \-L
Log directly.

.TP
.B \-O
Don\'t read settings, but use whatever is in the environment.

.TP
.BI \-o\  setting = value
Overrides the \fIsetting\fR from the current configuration with the given
\fIvalue\fR (can be specified multiple times). E.g. with \-o dsync_alt_char=c
one is able to overwrite the character to use as an replacement for all invalid
characters encountered within a mailbox name (per default \'\fB_\fR').
\" ./mail-options.inc

\" vim: ts=4 sw=4 filetype=nroff
.TP
.BI \-S\  socket
The option\'s argument \fIsocket\fR is either an absolute path to a local UNIX
domain socket, or a \fIhostname\fB:\fIport\fR pair,
in order to connect a remote host via a TCP socket.

This allows an administrator to execute
.BR doveadm (1M)
mail commands through the given socket.

.TP
.B \-A
Run this command for \fBall\fR 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 \fIfirst_valid_uid\fR setting.

When the SQL userdb module is used make sure that the \fIiterate_query\fR
setting in
.I /etc/dovecot/conf.d/sql.conf
matches your database layout.  When using the LDAP userdb module, make sure
that the \fIiterate_attrs\fR and \fIiterate_filter\fR settings in
.I /etc/dovecot/conf.d/ldap.conf
match your LDAP schema.  Otherwise
.BR doveadm (1M)
will be unable to iterate over \fBall\fR users.

.TP
.BI \-u\  user
Run this command for the specified \fIuser\fR, only.  It is also possible to
use \'\fB*\fR\' and \'\fB?\fR\' wildcards (e.g. \-u \e*@example.org).

When neither the \fB\-A\fR nor \fB\-u\ \fIuser\fR option was specified,
this command will be executed with the environment of the currently logged
in user, i.e. dovecot will use the value of the environment variable \fBUSER\fR
as user name. If it is unset, the command fails.

.P
Command specific options:

.TP
.B \-d
Delete the mailbox if it is empty after expunging.
.\"------------------------------------------------------------------------
.SH OPERANDS
.TP
.I search_query
Expunge messages matching this search query.
See
.BR doveadm\-search\-query (5)
for details.
.\"------------------------------------------------------------------------
.SH EXAMPLES
This example expunges messages from Spam mailbox that were saved/copied
there more than two weeks ago:

.RS 3
.nf
\fBdoveadm expunge \-u jane.doe@example.org mailbox Spam savedbefore 2w\fR
.fi
.RE
.\"------------------------------------------------------------------------
.SH SEE ALSO
.BR doveadm (1M),
.BR doveadm\-fetch (1M),
.BR doveadm\-purge (1M),
.BR doveadm\-search (1M),
.BR doveadm\-search\-query (5)
.\"------------------------------------------------------------------------
\" ./reporting-bugs.inc

.SH REPORTING BUGS
Report bugs, including \fBdoveconf \-n\fR
output, to the dovecot Mailing List <dovecot@dovecot.org>.
Information about reporting bugs is available at:
http://dovecot.org/bugreport.html