Dovecot mailbox list index cache invalidation on mailbox create, rename, or delete

Question

The goal is to keep IMAP LIST responses consistent immediately after a mailbox is created, renamed, or removed, without waiting for the mailbox list index TTL to expire or reloading the server.

Dovecot accelerates mailbox listings using a cached index. The cache lifetime appears to be governed by time-based expiration or manual refresh, but it is not clear whether Dovecot automatically invalidates affected entries when mailbox directories change. This uncertainty matters for shared mailboxes and dynamic namespace deployments where clients expect near-real-time visibility.

The configuration must avoid disabling the cache entirely, since LIST performance on large installations depends on it. Any invalidation mechanism should apply only to changed mailboxes rather than flushing the whole index.

Can mailbox list index entries be invalidated automatically when a mailbox is created, renamed, or deleted? Which Dovecot setting controls the refresh trigger for mailbox lifecycle events? Is a full service reload required for new mailboxes to appear in IMAP LIST output?

Tasadduq Burney · Answer

Immediate Invalidation for Dovecot-Managed Mailbox Changes

Mailbox list index entries are invalidated immediately when changes occur through Dovecot's own protocols. Creating, renaming, or deleting a mailbox via IMAP CREATE/RENAME/DELETE, LMTP delivery, or doveadm mailbox commands updates the index in the same transaction. No TTL expiration or server reload is required—clients will see the new state on the next LIST command.

External Filesystem Changes Require Refresh or Inotify

When mailbox directories are modified outside Dovecot (e.g., mkdir ~/Maildir/.externals, provisioning scripts, or shared storage synchronization), the index does not update instantly. Dovecot relies on two mechanisms to detect these changes:

Inotify/fanotify watches (Linux): These kernel-level watches detect filesystem events near-real-time for supported filesystems.
Periodic rescans controlled by mailbox_list_index_refresh_interval (default 30 seconds): If inotify is unavailable or the watch limit is exceeded, Dovecot falls back to polling.

Key Settings

Setting	Default	Purpose
`mailbox_list_index = yes`	yes (v2.3+)	Enables the cached mailbox list index for faster IMAP LIST responses.
`mailbox_list_index_refresh_interval`	30	Seconds between periodic filesystem rescans for external changes. Set to 0 to disable polling and rely solely on inotify.

Verification Steps

Protocol change test: Create a mailbox via IMAP (a CREATE testbox) and immediately issue a LIST "" "*". The mailbox appears without delay.
External change test: Create a mailbox directory externally (mkdir -p ~/Maildir/.extbox). Run a LIST "" "*"—the mailbox appears within mailbox_list_index_refresh_interval seconds or sooner if inotify delivers the event.
Diagnose refresh source: Enable log_debug = yes and mail_log_prefix in dovecot.conf. Look for mailbox_list_index: refreshed or inotify log lines.
Inspect index contents: Use doveadm dump index.list <user> to view on-disk index timestamps and entries.

Important Notes

A full Dovecot reload (doveadm reload or SIGHUP) is never required for mailbox list index updates. It only applies configuration changes.
NFS or network filesystems may not propagate inotify events; consider lowering mailbox_list_index_refresh_interval or scheduling periodic doveadm mailbox list -u <user> calls.
Inotify watch limits can be checked via cat /proc/sys/fs/inotify/max_user_watches. Exhaustion silently falls back to polling; monitor kernel logs and raise the limit for large installations.
To force an immediate index rebuild for a specific user after external changes, run doveadm mailbox list -u <user>, or on Dovecot v2.3.15+, use doveadm force-resync -u <user> mailbox_list_index.

Dovecot mailbox list index cache invalidation on mailbox create, rename, or delete