.\" Copyright (c) 2010-2013 Dovecot authors, see the included COPYING file
.TH DOVEADM\-MAILBOX 1M "2013-11-24" "Dovecot v2.2" "Dovecot"
.SH NAME
doveadm mailbox \- Commands related to handling mailboxes
.\"------------------------------------------------------------------------
.SH SYNOPSIS
.nh
.na
.HP
\" ./global-options-short.inc
\" ./master-options-short.inc
\" ./mail-options-short.inc
\fBdoveadm mailbox create\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] [\-g\ \fIguid\fR] [\-s] \fImailbox\fR ...
.HP
\" ./global-options-short.inc
\" ./master-options-short.inc
\" ./mail-options-short.inc
\fBdoveadm mailbox delete\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] [\-r] [\-s] \fImailbox\fR\ ...
.HP
\" ./global-options-short.inc
\" ./master-options-short.inc
\" ./mail-options-short.inc
\fBdoveadm mailbox list\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] [\-7|\-8] [\-s] [\fImailbox\fR]...
.HP
\" ./global-options-short.inc
\" ./master-options-short.inc
\" ./mail-options-short.inc
\fBdoveadm mailbox mutf7\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] [\-7|\-8] \fIname\fR\ ...
.HP
\" ./global-options-short.inc
\" ./master-options-short.inc
\" ./mail-options-short.inc
\fBdoveadm mailbox rename\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] \fIold_name\fR \fInew_name\fR
.HP
\" ./global-options-short.inc
\" ./master-options-short.inc
\" ./mail-options-short.inc
\fBdoveadm mailbox status\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] [\-t] \fIfields\fR \fImailbox\fR\ ...
.HP
\" ./global-options-short.inc
\" ./master-options-short.inc
\" ./mail-options-short.inc
\fBdoveadm mailbox subscribe\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] \fImailbox\fR\ ...
.HP
\" ./global-options-short.inc
\" ./master-options-short.inc
\" ./mail-options-short.inc
\fBdoveadm mailbox unsubscribe\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] \fImailbox\fR\ ...
.ad
.hy
.\"------------------------------------------------------------------------
.SH DESCRIPTION
These commands can be used to query and modify mailboxes.
.\"------------------------------------------------------------------------
.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:

.\"------------------------------------------------------------------------
.SH OPERANDS
.TP
.I mailbox
Is the name of a mailbox, as visible to IMAP clients, except in UTF\-8 format.
The hierarchy separator between a parent and child mailbox is
commonly \'\fB/\fR\' or \'\fB.\fR\', but this depends on your selected mailbox
storage format and namespace configuration. The mailbox names may also require
a namespace prefix.
.\"------------------------------------------------------------------------
.SH SUBCOMMANDS
.HP
.na
\" ./global-options-short.inc
\" ./master-options-short.inc
\" ./mail-options-short.inc
\fBmailbox create\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] [\-g\ \fIguid\fR] [\-s] \fImailbox\fR\ ...
.ad
.RS 3
.P
This command is used to create one or more mailboxes.
The mailbox format of the created mailboxes depends on the \fImail_location\fR
setting, or the user\'s \fBmail\fR field, returned by the userdb.

.TP
.BI \-g \ guid
Create the mailbox with the specified GUID.

.TP
.B \-s
Add the created mailboxes also to the user\'s subscriptions.
.RE
.sp 2

.HP
.na
\" ./global-options-short.inc
\" ./master-options-short.inc
\" ./mail-options-short.inc
\fBmailbox delete\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] [\-s] \fImailbox\fR\ ...
.ad
.RS 3
.P
This command deletes a mailbox and expunges all the messages it contains.
If the mailbox has any children, they won\'t be deleted.

.TP
.B \-s
Deleted mailboxes will be also unsubscribed.

.TP
.B \-r
Delete recursively.
.RE
.sp 2

.HP
.na
\" ./global-options-short.inc
\" ./master-options-short.inc
\" ./mail-options-short.inc
\fBmailbox list\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] [\-7|\-8] [\-s] [\fImailbox\fR]...
.ad
.RS 3
.P
To get an overview of existing mailboxes use this command.
It\'s also possible to use wildcards in the \fImailbox\fR name.

.TP
.B \-s
List subscribed mailboxes, only. Listed subscriptions may also contain
mailboxes that are already deleted.

.TP
.B \-7
Lists the mailboxes with mUTF\-7 encoding.

.TP
.B \-8
Lists the mailboxes with UTF\-8 encoding.
.RE
.sp 2

.HP
.na
\" ./global-options-short.inc
\" ./master-options-short.inc
\" ./mail-options-short.inc
\fBmailbox mutf7\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] [\-7|\-8] \fIname\fR\ ...
.ad
.RS 3
.P
This command may be used to convert the international mailbox \fIname\fR
into a modified version of the UTF\-7 encoding and vice versa.
See RFC 3501, section 5.1.3 (Mailbox International Naming Convention).

.TP
.B \-7
The \fIname\fR\'s string representation is mUTF\-7 encoded
and should be converted to UTF\-8.

.TP
.B \-8
The \fIname\fR\'s string representation is UTF\-8 encoded
and should be converted to mUTF\-7 (default).
.RE
.sp 2

.HP
.na
\" ./global-options-short.inc
\" ./master-options-short.inc
\" ./mail-options-short.inc
\fBmailbox rename\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] [\-s] \fIold_name\fR \fInew_name\fR
.ad
.RS 3
.P
This command is used to rename the mailbox \fIold_name\fR to \fInew_name\fR.

When the \fB\-s\fR option is given, \fIold_name\fR will be unsubscribed
and \fInew_name\fR will be subscribed.
.RE
.sp 2

.HP
.na
\" ./global-options-short.inc
\" ./master-options-short.inc
\" ./mail-options-short.inc
\fBmailbox status\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] [\-t] \fIfields\fR \fImailbox\fR\ ...
.ad
.RS 3
.P
Show the status of one or more mailboxes.  The \fImailbox\fR
name may also contain wildcards.

This command uses by default the output \fBformatter flow\fR.

.TP
.B \-t
Summarize the values of the status fields
\fBmessages\fR, \fBrecent\fR, \fBunseen\fR and \fBvsize\fR
of multiple mailboxes to a sum (total).

.TP
.I fields
Specify the status fields which should be shown.
In order to specify multiple status fields, enclosed them in quotes.
.RS
.TP 2
.B all
This is a special status field name.  It means show all of the fields shown
below.  When the \fB\-t\fR option is present, it means show only the
\fBmessages\fR, \fBrecent\fR, \fBunseen\fR and \fBvsize\fR fields.
.TP
.B guid
The \fImailbox\fR\'s globally unique identifier.
.TP
.B highestmodseq
The highest mod\-sequence value of all messages in the \fImailbox\fR.
.TP
.B messages
The number of messages in the \fImailbox\fR.
.TP
.B recent
The number of messages with the \fBRecent\fR flag set.
.TP
.B uidnext
The next unique identifier value.
.TP
.B uidvalidity
The unique identifier validity value.
.TP
.B unseen
The message sequence number of the first unseen message in the \fImailbox\fR.
.TP
.B vsize
The \fImailbox\fR\'s virtual size, computed with CRLF line terminators.
.RE
.sp 2

.HP
.na
\" ./global-options-short.inc
\" ./master-options-short.inc
\" ./mail-options-short.inc
\fBmailbox subscribe\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] \fImailbox\fR\ ...
.ad
.RS 3
.P
This command is used to subscribe one or more mailboxes.
.RE
.sp 2

.HP
.na
\" ./global-options-short.inc
\" ./master-options-short.inc
\" ./mail-options-short.inc
\fBmailbox unsubscribe\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] \fImailbox\fR\ ...
.ad
.RS 3
.P
This command is used to unsubscribe one or more mailboxes.
.RE
.\"------------------------------------------------------------------------
.SH EXAMPLES
List subscribed mailboxes, beginning with \'dovecot\', of user bob:

.RS 3
.nf
.B doveadm mailbox list \-s \-u bob dovecot*
dovecot
dovecot/pigeonhole
dovecot/pigeonhole/2.0
.fi
.RE
.\"-------------------------------------
.PP
Now have a look at the status of user bob\'s dovecot mailboxes:

.RS 3
.nf
.B doveadm \-f table mailbox status \-u bob "messages vsize" dovecot*
mailbox                                    messages vsize
dovecot                                    20501    93968492
dovecot/pigeonhole                         0        0
dovecot/pigeonhole/2.0                     47       323474
.fi
.RE
.\"-------------------------------------
.PP
Converting an internationalized mailbox name from mUTF\-7 to UTF\-8 and
vice versa:

.RS 3
.nf
.B doveadm mailbox mutf7 \-7 ~peter/mail/&U,BTFw\-/&ZeVnLIqe\-
~peter/mail/台北/日本語

.\" The used UTF-8 chars cause screen garbage if printed as bold.
.\" So separate them and print with normal face!
.B doveadm mailbox mutf7 ~peter/mail/\c
台北/日本語
~peter/mail/&U,BTFw\-/&ZeVnLIqe\-
.fi
.RE
.\"------------------------------------------------------------------------
.SH SEE ALSO
.BR doveadm (1M)
.\"------------------------------------------------------------------------
\" ./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