DOVEADM-FETCH(1)

💖 DOVEADM-FETCH 💖

okay bestie, welcome to doveadm-fetch — it lives in the Dovecot manual (section 1, for the curious 👑), and it's literally the tool that goes and gets stuff out of your users' mailboxes. no cap.

---

✨ NAME ✨

doveadm-fetch — fetch partial/full messages or message information 🦋

---

🌸 SYNOPSIS 🌸

doveadm [GLOBAL OPTIONS] [-f formatter] fetch [-S socket_path] -A fields
search_query

doveadm [GLOBAL OPTIONS] [-f formatter] fetch [-S socket_path] -F file
fields search_query

doveadm [GLOBAL OPTIONS] [-f formatter] fetch [-S socket_path] --no-
userdb-lookup fields search_query

doveadm [GLOBAL OPTIONS] [-f formatter] fetch [-S socket_path] -u user
fields search_query

---

💅 DESCRIPTION 💅

doveadm fetch is your main character for grabbing message contents and metadata. it's giving extremely useful for scripts and for debugging — like, if you need to peek at what's actually inside a mailbox, this is the move. 🔥

if you wanna fetch messages one at a time, go look at doveadm-search(1) instead, bestie.

• Please respect your users' privacy. 🙈 (yes, this is a real bullet in the original and yes, it matters. be a decent person.)

---

🌈 GLOBAL OPTIONS 🌈

the global doveadm(1) options, here for you:

• -D — turns on verbosity AND debug messages. full yapping mode, but make it diagnostic. ✨
• -O — do not read any config file, just use defaults. the dovecot_storage_version setting defaults to the latest version, but you can override it with -o. (iconic raw-dogging-the-config energy.)
• -k — preserve the entire environment for doveadm, not just the import_environment setting. give it everything, no crumbs. 🫶
• -v — enables verbosity, including a progress counter. so you can watch it cook. 💅
• -i instance-name — if you're running multiple Dovecot instances, pick the config file based on this instance name.

See the instance_name setting for more info.

• -c config-file — read configuration from the given config-file. by default it first reads the config socket, then falls back to /etc/dovecot/dovecot.conf. you can also point this at the config socket of some instance running a compatible version. 🎀
• -o setting=value — overrides the configuration setting from /etc/dovecot/dovecot.conf and from the userdb with the given value. wanna override multiple settings? just use -o multiple times, she's repeatable. 💖
• -f formatter — specifies the formatter for formatting the output. supported formatters are:
  • flow — prints each line with key=value pairs.
  • json — prints a JSON array of JSON objects.
  • pager — prints each key: value pair on its own line and separates records with form feed character (^L).
  • tab — prints a table header followed by tab separated value lines.
  • table — prints a table header followed by adjusted value lines.

this command uses by default the output formatter pager. ✨ (yes that's a real quirk of the formatting in the original, and yes, pager is your default, periodt.)

---

🎀 OPTIONS 🎀

• -A — if the -A option is present, the command will be performed for all users. using this option in combination with system users from userdb { driver = passwd } is not recommended, because it contains also users with a lower UID than the one configured with the first_valid_uid setting. ⚠️

when the SQL userdb module is used, make sure that the userdb_sql_iterate_query setting setting matches your database layout.

when using the LDAP userdb module, make sure that the userdb_fields setting and userdb_ldap_iterate_fields setting settings match your LDAP schema. otherwise doveadm(1) will be unable to iterate over all users. 😭

• -F file — execute the command for all the users in the file. this is similar to the -A option, but instead of getting the list of users from the userdb, they are read from the given file. the file contains one username per line. 📄
• --no-userdb-lookup — do not perform userdb lookup. use the USER environment variable to specify the username. 🦋
• -S socket_path — the option's argument is either an absolute path to a local UNIX domain socket, or a hostname and port (hostname:port), in order to connect a remote host via a TCP socket.

this allows an administrator to execute doveadm(1) mail commands through the given socket. 🌐

• -u user/mask — run the command only for the given user. it's also possible to use '*' and '?' wildcards (e.g. -u *@example.org). 🎯

---

🦋 ARGUMENTS 🦋

fields

one or more result field names to display, if the search_query matches any messages. in order to specify multiple fields, enclose them in single or double quotes. ✨

supported fields are:

binary : Message body in decoded format.

binary.<section> : Part of the body decoded, e.g. binary.1

body : The body of a message.

body.<section> : Part of the body, e.g. body.1

body.preview : Short preview of the body.

body.snippet : Old alias for preview.

date.received : Date and time of final delivery, when the message
was delivered to a user's mailbox for the first time.

The internal date and time of the source message, when the message
was copied by the IMAP COPY command.

The date-time attribute when present, otherwise the current time,
when the message was saved by the IMAP APPEND command.

date.received.unixtime : date.received as unix timestamp.

date.saved : Date and time when the message was saved to mailbox.

date.saved.unixtime : date.saved as unix timestamp.

date.sent : Date and time of the message's Date: header.

date.sent.unixtime : date.sent as unix timestamp.

flags : A message's IMAP flags, e.g. \Seen

guid : A message's globally unique identifier.

hdr : The header of the message.

hdr.<name> : Named header from the message.

imap.body : IMAP BODY output of the message (see RFC 3501).

imap.bodystructure : IMAP BODYSTRUCTURE output of the message (see
RFC 3501).

imap.envelope : IMAP ENVELOPE output of the message (see RFC 3501).

mailbox : Name of the mailbox, in which the message is stored. The
name is in UTF-8.

mailbox-guid : The globally unique identifier of the mailbox, in
which the message is located.

modseq : Modification sequence number for the mail.

pop3.order : A message's order number within a mailbox.

pop3.uidl : A message's unique (POP3) identifier within a mailbox.

refcount : Mail reference count, mdbox only.

seq : A message's sequence number in a mailbox.

size.physical : A message's physical size.

size.virtual : A message's virtual size, computed with CRLF line
terminators.

storageid : Mailbox driver specific ID for the mail.

text : The entire message (header and body).

text.utf8 : The entire message (header and body) — UTF-8 encoded.

uid : A message's unique (IMAP) identifier in a mailbox.

user : A message owner's login name.

search_query

fetch messages matching this search query. see doveadm-search-query(1) for details. 🔍

---

🔥 EXAMPLE 🔥

this example is based on the first example from doveadm-search(1). we are fetching the fields mailbox and date.sent from user bob's mailbox with the guid "3a94c928d66ebe4bda04000015811c6a" for the messages with the UIDs 8, 25 and 45. 💖

doveadm fetch -u bob "mailbox date.sent" 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)

ate. 💅

---

😭 REPORTING BUGS 😭

report bugs, including doveconf -n output, to the Dovecot Mailing List ⟨dovecot@dovecot.org⟩. information about reporting bugs is available at: ⟨https://dovecot.org/bugreport.html⟩ 🫶

---

🌟 SEE ALSO 🌟

doveadm(1) ✨

---

okay that's the whole page bestie, no skips, no crumbs 🎀 — this one's from the Dovecot source, revision f979264, dated April 2026. go fetch something iconic. 💖✨🦋