CTL_MBOXLIST(8)

📦
version 3.12.3 · 6 versions
, in ubuntu stonking

💖 CTL_MBOXLIST 💖

okay bestie, listen — this is ctl_mboxlist, part of the Cyrus IMAP docs, and it is literally your remote control for the mailbox list database. That's the big book of who-has-what-mailbox. Let's get into it 🎀

🌸 NAME 🌸

ctl_mboxlist — Cyrus IMAP documentation

It does operations on the mailbox list database. That's the whole job. Slay.

✨ SYNOPSIS ✨

ctl_mboxlist [ -C config-file ] -d [ -x ] [-y] [ -p partition ] [ -f filename ]
ctl_mboxlist [ -C config-file ] -u [ -f filename ] [ -L ]
ctl_mboxlist [ -C config-file ] -m [ -a ] [ -w ] [ -i ] [ -f filename ]
ctl_mboxlist [ -C config-file ] -v [ -f filename ]

like, four whole modes of existence 💅

🦋 DESCRIPTION 🦋

So ctl_mboxlist does various administrative operations on the mailbox list database. That's its whole personality and it's thriving.

It reads its config options out of the imapd.conf(5) file — unless you tell it otherwise with -C. And the configdirectory option in imapd.conf(5)? That's what decides where the mailboxes database lives by default. iykyk 📁✨

💅 OPTIONS 💅

  • -C config-file — use config-file as the config file instead of the default imapd.conf(5). you're the boss 🫶
  • -d, --dump — dump the contents of the database to standard output, in JSON format. gorgeous, structured, iconic 🌈
  • -x, --remove-dumped — when you're doing a dump, also remove the mailboxes you just dumped from the mailbox list. mostly useful when you pair it with -p. it's giving "cleanup era" 🧹
  • -y, --include-intermediaries — when doing a dump, also list the intermediary mailboxes that would normally be hidden from IMAP. no more secret folders, we're airing everything out 👑
  • -p partition, --partition=partition — when doing a dump, only dump the mailboxes that live on partition. picky and we respect it 💖
  • -f filename, --filename=filename — use the database at filename instead of the default (configdirectory/mailboxes.db*). ⭐
  • -L, --legacy — when doing an undump, use the legacy dump parser instead of the JSON parser. supposedly useful for importing a dump made by an older version of Cyrus. vintage vibes, respect the elders 🙈
  • -u, --undump — load ("undump") the contents of the database from standard input. the input MUST be a valid JSON file — unless you also passed -L.
IMPORTANT: USE THIS OPTION WITH CARE. If you modified the dump file since it was dumped, or if the file wasn't produced by -d in the first place, or it was produced on a different server — you can easily break your mailboxes.db. Undump will refuse to process a syntactically-invalid dump file, but it can't do much to protect you from a valid file containing bad data. 😭 fr fr be careful
  • -m, --sync-mupdate — for backend servers in the Cyrus Murder, synchronize the local mailbox list file with the MUPDATE server. server-to-server gossip, but make it productive 🌸
  • -a, --authoritative — when used with -m, assume the local mailboxes file is authoritative. that means: only change the mupdate server, do not delete any local mailboxes.
IMPORTANT: USE THIS OPTION WITH CARE, as it allows namespace collisions into the murder. 💀 we do not play with this one
  • -w, --warn-only — when used with -m, print out what would be done but do not actually perform the operations. a dress rehearsal, a mood board, a vision ✨
  • -i, --interactive — when used with -m, asks for verification before deleting local mailboxes. consent is key bestie 🫶
  • -v, --verify — verify the consistency of the mailbox list database and the spool partition(s). Mailboxes that are in the database but not located on a spool partition, and those that are located on a spool partition (a directory containing a valid cyrus.header file) but not present in the database, will be reported. Note that this function is very I/O intensive. it will absolutely devour your disk, no cap 😳

🎀 EXAMPLES 🎀

ctl_mboxlist -d

Dump the mailboxes list to standard output in JSON format. pretty printer behavior, honestly 🌈

ctl_mboxlist -u < newmboxlist.dump

Undump (restore) the mailboxes database from newmboxlist.dump, where newmboxlist.dump is a JSON file produced by ctl_mboxlist -d.

NOTE: Be very careful with this option. 😭
ctl_mboxlist -m

Synchronize our mailboxes database with the MUPDATE server. (One may commonly put a command like this into the START section of cyrus.conf(5) on backend nodes of a Murder cluster, to cause the backend to synchronize its mailbox list with the mupdate master upon startup.) set it and forget it era 💅

ctl_mboxlist -m -w

The same as above, but only show us what would be done, don't actually do it. window shopping 🛍️

ctl_mboxlist -m -a

Populate the Mupdate server from our copy of the mailboxes database.

NOTE: Be very careful with this option, as it can create conflicts in the Murder. 💀
ctl_mboxlist -m -i

Synchronize our mailboxes database with the MUPDATE server interactively, asking for verification before deleting any local mailboxes. polite and powerful, the dream combo 👑

🧸 FILES 🧸

  • /etc/imapd.conf
  • <configdirectory>/mailboxes.db

the sacred texts 📜

🦄 SEE ALSO 🦄

go read those too, bestie, they're part of the lore 🫶

👑 AUTHOR 👑

The Cyrus Team, Nic Bernstein (Onlight), Jeroen van Meeuwen (Kolab Systems)

1993–2026, The Cyrus Team

and that's the whole page, periodt ✨ this was Cyrus IMAP version 3.12.3, dated Jul 15, 2026 — go forth and do not break your mailboxes.db 💖🎀🦋

📦 where this page comes from