DOVEADM-EXPUNGE(1)

💖 DOVEADM-EXPUNGE 💖

okay bestie, gather round, because today we're learning about doveadm-expunge — one of the doveadm(1) girlies, straight outta the Dovecot family. this one expunges messages matching a given search query. it's giving janitor energy but make it couture. 🧹✨

---

🌸 NAME 🌸

doveadm-expunge — expunge messages matching given search query

---

✨ SYNOPSIS ✨

doveadm [GLOBAL OPTIONS] expunge [-S socket_path] [-d] -A search_query

doveadm [GLOBAL OPTIONS] expunge [-S socket_path] [-d] -F file search_query

doveadm [GLOBAL OPTIONS] expunge [-S socket_path] [-d] --no-userdb-lookup search_query

doveadm [GLOBAL OPTIONS] expunge [-S socket_path] [-d] -u user search_query

four whole forms, she's versatile like that 💅

---

🦋 DESCRIPTION 🦋

so like, this command expunges mails that match the search query you give it. that's the whole vibe. it's typically used to yeet old mails out of users' Trash and/or Spam mailboxes, which honestly? iconic. trash day but it's automated.

not me about to tell you the most important part: if you wanna test which messages a given search query would match before you nuke them, go use doveadm fetch or doveadm search first. bestie. PLEASE. do the vibe check first. 🙈

okay so the four forms, one by one:

• first form — the command runs for all users. everybody. the whole group chat.
• second form — doveadm(1) expunges messages of the users listed in the given file.
• third form — the command runs for the user contained in the USER environment variable.
• final form — only the matching mails of the given user(s) get expunged. just them. nobody else. periodt.

---

👑 GLOBAL OPTIONS 👑

these are the global doveadm(1) options, so they're like, the shared fit that every doveadm command wears 💜

• -D — turns on verbosity AND debug messages. she's chatty and she's telling you everything.
• -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. (yes, defaults-only mode. feral. love that for her.)
• -k — preserve the entire environment for doveadm, not just the import_environment setting.
• -v — enables verbosity, including a progress counter. progress bar slay 📈
• -i instance-name — if you're running multiple Dovecot instances, choose 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 config socket, and 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. to override multiple settings, you can specify the -o option multiple times. stack 'em like bracelets. 🎀

---

💅 OPTIONS 💅

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

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. and then she's just sitting there like 🧍‍♀️

• -d — delete the mailbox if it is empty after expunging. if it's empty, it's gone-gone. bye mailbox 💀
• -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. one per line bestie, don't get cute with it.
• --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. remote queen behavior 🔥

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

---

🌈 ARGUMENTS 🌈

search_query

expunge messages matching this search query. see doveadm-search-query(7) for details.

A mailbox parameter is REQUIRED. 👀

A message range limiter is REQUIRED. in other words, you must have at least one query parameter that limits the message range. if all messages are needed, the "all" query parameter can be used. no accidentally expunging the entire mailbox, we are NOT doing that today. 🙅‍♀️

---

🍓 EXAMPLE 🍓

this example expunges messages from the Spam mailbox that were saved/copied there more than two weeks ago:

doveadm expunge -u jane.doe@example.org mailbox Spam savedbefore 2w

look at that. clean. savedbefore 2w. two weeks of spam, evaporated. she ate. 💅

---

😭 REPORTING BUGS 😭

found a bug? report it — including doveconf -n output — to the Dovecot Mailing List ⟨dovecot@dovecot.org⟩.

info about reporting bugs lives at: ⟨https://dovecot.org/bugreport.html⟩

(and yes, include the doveconf -n output, they will ask for it, save yourself the round trip bestie 🫶)

---

🔥 SEE ALSO 🔥

• doveadm(1)
• doveadm-search(1)

---

and that's the whole page, bestie!! 🎀 this one's from the Dovecot manual, page revision f979264, dated April 2026. mwah. go expunge responsibly. 🦋💖✨