Maildir
-------

We support Courier-compatible Maildir++. INBOX is the ~/Maildir directory,
all the other folders named as ".<folder>.<subfolder>.<etc>" under it, any
directories not starting with a dot are simply ignored. Deleting folders is
made atomic by renaming them as "..<folder name>" and deleting the
directory after that. So, all directories beginning with ".." are deleted
whenever they're noticed. Indexes are stored into each folder's root
directory.

Custom flags saved using a..z letters as Maildir file flags. .customflags
file is then used to map the letters to names (a=0, b=1, etc).


mbox
----

mbox storage currently requires that all mail is in user-writable
directory, eg. ~/mail. Especially using /var/mail/user is NOT supported.
You may however create a ~/mail/inbox hardlink (or symlink if not chrooted)
to pointing to /var/mail/user. All files in the mail directory are
considered as mailboxes. Directories specify subfolders in IMAP. "inbox"
file specifies the INBOX folder and can not be named otherwise. Indexes are
stored into ".imap/<mailbox name>/" directories.


Detecting what to use
---------------------

imap process detects the storage from MAIL-environment. It's preferred
format is "<storage>:<data>", for example "maildir:~/Maildir". It's anyway
allowed to be in pretty much any format as long as some of the storages
recognizes it as a valid data, so for example "MAIL=~/mail" is first
checked by maildir storage to see if it's valid maildir and mbox storage
after that.

If the MAIL environment isn't given at all, all storages are gone through
and asked if they can find a usable mail folder. Also as a special case, if
MAILDIR environment exists, maildir storage is used with the directory
specified in it.

Maildir storage is autodetected by checking if <directory>/cur/ exists and
we have rwx access to it. If directory isn't known, / and ~/Maildir are
checked. / is checked because we could be chrooted.

mbox storage is autodetected by checking if .imap/ (+rwx), inbox (+rw) or
mbox (+rw) exists in directory. If directory isn't known, / is tried first.
After that, ~/mail and ~/Mail directories are used.


Files created by Dovecot
------------------------

.subscriptions: One folder per line listing subscribed IMAP folders.
There's only one of these files in the root mail directory (~/Maildir/ or
~/mail/.imap/).

Then there's the per-folder files:

.imap.index: Fixed width mail index records.

.imap.index.data: Variable width data, for example mail file name and
cached body, envelope, etc.

.imap.index.log: Log file describing made changes. This file is used to
mark external changes (expunges and flag changes) temporarily until they're
synced into IMAP clients. If multiple Dovecots have the same folder open,
this can be a big speedup.

.imap.index.tree: Binary tree used for looking up messages from .imap.index
file. This is used for both UID lookups and message sequence lookups.
Sequences can be looked up directly from the index as long as no messages
have been expunged, but after that it gets slow unless it's compressed.
Using this file however can keep the sequence lookups and expunges fast in
all situations without requiring compression.

.customflags: Lists custom message flags. First line is header which
Dovecots check to see if the file has changed. Other lines list the flags
in format "<flag number> <flag name>". Currently there can be 26 different
flags (0..25).

.imap.index.log and .imap.index.tree files can be deleted without any data
loss, they're simply recreated/rebuilt when they're noticed missing.

Deleting .imap.index and .imap.index.data files results in loss of message
UIDs. That may be a bad thing with some IMAP clients which store some data
about message locally and identifies the message by it's UID.

Deleting .customflags results in loss of custom flag names for Maildir.
With mbox the .customflags is simply recreated based on the flags listed
in the mbox file itself (ie. no data loss).