This documentation is for Dovecot v2.x, see wiki1 for v1.x documentation.

Virtual mailboxes

First, you'll have to load the plugin:

mail_plugins = $mail_plugins virtual

Namespace configuration

Then, you'll have to create a namespace for the virtual mailboxes, for example:

namespace {
  prefix = virtual/
  separator = /
  location = virtual:~/Maildir/virtual

After this you can create virtual mailboxes under ~/Maildir/virtual. By default it uses the "fs" layout, so you can create directories such as:

If you prefer to use Maildir++ layout instead, you can simply append :LAYOUT=maildir++ to the location.

Virtual mailbox configuration

For each virtual directory you need to create a dovecot-virtual file. Its syntax is like:

<1+ mailbox patterns>
  <search program>
[<more mailbox patterns>
  <search program for these mailboxes>

Mailbox patterns can contain IMAP LIST-compatible "*" and "%" wildcards. They are currently evaluated only when the virtual mailbox is being selected, so if more mailboxes are created during that they aren't noticed.

"*" wildcard matches only one namespace at a time based on the namespace prefix. For example if you have namespaces with an empty prefix and a prefix "mail/":

Beware that "*" will not match any mailbox which already has a more specialised match!

The mailbox names have special prefixes:

If you need to actually include a mailbox name that contains such prefix, you can currently just kludge it by using '+' prefix (if you don't care about the \Recent flags) and adding the mailbox name after that (e.g. "+-box").

Search program is compatible with IMAP SEARCH command. Besides the standard SEARCH key you may want to use X-MAILBOX key which matches the message's original mailbox. Note the leading whitespace in front of search specifications.

Saving mails to virtual mailboxes

It's possible to configure virtual mailbox so that it's possible to save/copy messages there. This is done by specifying a single physical mailbox where the message is really saved by prefixing it with '!', e.g.:


Note however that nothing guarantees that the saved mail will actually show up in the virtual mailbox. If a message was saved with \Seen flag to the above virtual mailbox, it wouldn't show up there. This also means it's problematic to support IMAP UIDPLUS extension for virtual mailboxes, and currently Dovecot doesn't even try (no [APPENDUID] or [COPYUID] is sent to client).

The !-prefixed virtual mailbox is also selected from; you don't need to list it again without an ! or you'll get two copies of your messages in the virtual mailbox.

Mailbox selection base on metadata (v2.2.22+)

Instead of a mailbox name, you can specify a metadata filter:


There can be multiple metadata entries. All the entries must match.

For example:


This matches all mailboxes, which contain a virtual METADATA entry that has any value except "ignore".


# ~/Maildir/virtual/Trash/dovecot-virtual

# ~/Maildir/virtual/unseen/dovecot-virtual

# ~/Maildir/virtual/all/dovecot-virtual

# ~/Maildir/virtual/INBOX/dovecot-virtual
  inthread refs x-mailbox INBOX

# ~/Maildir/virtual/all/dovecot-virtual

# ~/Maildir/virtual/Sentmail/dovecot-virtual

# ~/Maildir/virtual/recent/dovecot-virtual
  all younger 172800

# ~/Maildir/virtual/example/dovecot-virtual
  or unseen flagged

Virtual POP3 INBOX

If you want POP3 INBOX to contain some or all mailboxes, you can do this in the following way:

Namespace configuration:

# The default namespace that is visible to IMAP clients
namespace inbox {
  prefix =
  separator = /
  list = yes

# Virtual namespace for the virtual INBOX. Use a global directory for dovecot-virtual files.
namespace virtual {
  prefix = virtual/
  separator = /
  location = virtual:/etc/dovecot/virtual:INDEX=~/Maildir/virtual
  list = no
  hidden = yes

# Copy of the inbox namespace. We'll use this in dovecot-virtual file.
namespace real {
  prefix = RealMails/
  separator = /
  list = no
  hidden = yes

Note that none of the namespaces have inbox=yes. This is because for IMAP users you want the inbox namespace to have inbox=yes, but for POP3 users you want the virtual namespace to have inbox=yes. This requires setting the inbox=yes in userdb extra fields. For example with MySQL you can can do this like:

user_query = SELECT ..., \
  CASE '%s' WHEN 'pop3' THEN NULL ELSE 'yes' END AS 'namespace/inbox/inbox', \
  CASE '%s' WHEN 'pop3' THEN 'yes' ELSE NULL END AS 'namespace/virtual/inbox' \
  WHERE ...

Finally specify what the virtual INBOX looks like for POP3 users:

/etc/dovecot/virtual/INBOX/dovecot-virtual :


You'll have to use the RealMails/ prefix if you want to use "*" wildcard, otherwise it would match INBOX, which in turn would again lead to the virtual INBOX and that would create a loop.

Also to avoid accidental POP3 UIDL changes, you shouldn't base the UIDLs on IMAP UIDs. Instead use for GUIDs (with maildir the same as base filename):

pop3_uidl_format = %g

Plugins/Virtual (last edited 2016-03-03 22:21:43 by TimoSirainen)