.\" Copyright (c) 2010 Dovecot authors, see the included COPYING file
.TH DOVEADM\-FETCH 1M "2010-11-25" "Dovecot v2.0" "Dovecot"
.SH NAME
doveadm\-fetch \- Fetch partial/full messages or message information
.\"------------------------------------------------------------------------
.SH SYNOPSIS
.BR doveadm " [" \-Dv "] [" \-f
.IR formatter ]
.BR fetch " [" \-S
.IR socket_path "] " "fields search_query"
.br
.\"-------------------------------------
.BR doveadm " [" \-Dv "] [" \-f
.IR formatter ]
.BR fetch " [" \-S
.IR socket_path "]"
.BI \-A " fields search_query"
.br
.\"-------------------------------------
.BR doveadm " [" \-Dv "] [" \-f
.IR formatter ]
.BR fetch " [" \-S
.IR socket_path "]"
.BI \-u " user fields search_query"
.\"------------------------------------------------------------------------
.SH DESCRIPTION
.B doveadm fetch
can be used to fetch messages\(aq contents and metadata. This can be useful
for scripts and for debugging. If you want to fetch messages one at a time,
see
.BR doveadm\-search (1M).
.IP Important:
Please respect your users\(aq privacy.
.\"------------------------------------------------------------------------
.SH OPTIONS
Global
.BR doveadm (1M)
.IR options :
.TP
.B \-D
Enables verbosity and debug messages.
.TP
.BI \-f\  formatter
Specifies the
.I formatter
for formatting the output.
Supported formatters are:
.RS
.TP
.B flow
prints each line with
.IB key = value
pairs.
.TP
.B pager
prints each
.IR key :\  value
pair on its own line and separates records with form feed character
.RB ( ^L ).
.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.
.\" --- command specific options --- "/.
.PP
This command uses by default the output formatter
.BR pager .
.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/conf.d/dovecot\-sql.conf
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/conf.d/dovecot\-ldap.conf
match your LDAP schema.
Otherwise
.BR doveadm (1M)
will be unable to iterate over all users.
.\"-------------------------------------
.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 (1M)
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
.BI \-u\  user
was specified, the
.I command
will be executed with the environment of the
currently logged in user.
.\"------------------------------------------------------------------------
.SH ARGUMENTS
.TP
.I fields
One or more result field names to display, if the
.I search_query
matches any messages.
In order to specify multiple fields, enclose them in single or double
quotes.
.br
Supported
.I fields
are:
.RS
.TP
.B body
.\"-----------------
The body of a message.
.TP
.B date.received
Date and time of final delivery, when the message was delivered to a
user\(aqs mailbox for the first time.
.br
The internal date and time of the source message, when the message was
copied by the IMAP COPY command.
.br
The date\-time attribute when present, otherwise the current time, when the
message was saved by the IMAP APPEND command.
.\"-----------------
.TP
.B date.saved
Date and time when the message was saved to mailbox.
.\"-----------------
.TP
.B date.sent
Date and time of the message\(aqs Date: header.
.\"-----------------
.TP
.B flags
A message\(aqs IMAP flags, e.g. \(rsSeen
.\"-----------------
.TP
.B guid
A message\(aqs globally unique identifier.
.\"-----------------
.TP
.B hdr
The header of the message.
.\"-----------------
.TP
.B imap.body
IMAP BODY output of the message (see RFC 3501).
.\"-----------------
.TP
.B imap.bodystructure
IMAP BODYSTRUCTURE output of the message (see RFC 3501).
.\"-----------------
.TP
.B imap.envelope
IMAP ENVELOPE output of the message (see RFC 3501).
.\"-----------------
.TP
.B mailbox
Name of the mailbox, in which the message is stored. The name is in UTF\-8.
.\"-----------------
.TP
.B mailbox\-guid
The globally unique identifier of the mailbox, in which the message is
located.
.\"-----------------
.TP
.B seq
A message\(aqs sequence number in a mailbox.
.\"-----------------
.TP
.B size.physical
A message\(aqs physical size.
.\"-----------------
.TP
.B size.virtual
A message\(aqs virtual size, computed with CRLF line terminators.
.\"-----------------
.TP
.B text
The entire message (header and body).
.\"-----------------
.TP
.B uid
A message\(aqs unique (IMAP) identifier in a mailbox.
.\"-----------------
.TP
.B user
A message owner\(aqs login name.
.\"-----------------
.RE
.\"-------------------------------------
.TP
.I search_query
Fetch messages matching this search query.
See
.BR doveadm\-search\-query (5)
for details.
.\"------------------------------------------------------------------------
.SH EXAMPLE
This example based on the first example from
.BR doveadm\-search (1M).
We are fetching the fields
.BR mailbox\  and\  date.sent
from user bob\(aqs mailbox with the guid
\(dq3a94c928d66ebe4bda04000015811c6a\(dq for the messages with the
UIDs
.BR 8 ,\  25 \ and \ 45 .
.PP
.nf
.B doveadm fetch \-u bob \(dqmailbox date.sent\(dq \(rs
.B mailbox\-guid 3a94c928d66ebe4bda04000015811c6a uid 8,25,45
mailbox: dovecot/pigeonhole/2.0
date.sent: 2010\-01\-19 01:17:41 (+0100)
^L
mailbox: dovecot/pigeonhole/2.0
date.sent: 2010\-01\-28 09:38:49 (+0100)
^L
mailbox: dovecot/pigeonhole/2.0
date.sent: 2010\-03\-28 18:41:14 (+0200)
^L
.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 (1M),
.BR doveadm\-search (1M),