This document describes the generic mail folder structure IMAPdir.

The goal of the work behind this specification is to provide the community with an unambiguous representation of a mailbox hierarchy where a mailbox name has a one-to-one match against a file system representation. The hierarchy and naming style is inspired by the IMAP4 protocol.

Rather than being a completely new mailbox format, this specification sets conventions on how to represent a mailbox hierarchy on a file system, using existing mailbox formats. IMAPdir is not bound to any protocol.

IMAPdir works with any mailbox format where one mailbox can be identified by a file, a directory or a symbolic link. One entry in an IMAPdir folder is a candidate for a mailbox. If the IMAPdir client can not identify a directory entry as a selectable mailbox, then the client must either skip the entry or mark it as invalid (in IMAP, marked as \NoSelect).

• There is no limitation to the type of file system or the number of file systems represented inside an IMAPdir.
• There are no reserved ordinary folder names such as "Sent", "Draft" or "Trash".
• Clients of the mailboxes inside an IMAPdir folder must follow the respective format and protocol conventions strictly.

The format of a mailbox representation in IMAPdir is a sequence of one or more US-ASCII characters (32-126), encoded using the following rules:

• A dot '.' character represents a soft hierarchy delimiter with two exceptions:
  • A leading dot represents the dot itself.
  • A dot '.' preceded by a backslash '\' represents the dot '.' itself.
• A backslash '\' preceded by a backslash '\' represents the backslash '\' itself. For all other cases than before a dot '.' or a backslash '\', a stray backslash '\' character is considered an error.
• A backslash '\' as the first character of an entry is considered an error.
• All other characters represent themselves.

Note that the protocol used to fetch the mailbox using the structuring IMAPdir convention may restrict the character set allowed. The clients must in those cases translate the mailbox names to a selectable format.

As with Maildir++, submailboxes can not be represented in a recursive fashion in the file system. The mailbox' representation name will contain the soft hierarchy delimiter character dot '.', and all mailboxes must reside in the same root level directory.

The following example shows the typical content of an IMAPdir stored under the directory mail/. The file system column displays the contents as viewed by the UNIX command 'ls -al -F'.

File system	IMAP	Description
mail/INBOX -> /var/mail/paul mail/INBOX.old/ -> ../Maildir/ mail/INBOX.outbox/ mail/work mail/3rd\. of July mail/Sent.2003.Jan/ mail/Sent.2003.Feb/ mail/Sent.2003.Mar/ mail/.foo	"INBOX" "INBOX/old" "INBOX/outbox" "work" "3rd. of July" "Sent/2003/Jan" "Sent/2003/Feb" "Sent/2003/Mar" ".foo"	Symbolic link to mbox Symbolic link to Maildir Maildir mbox mbox Maildir Maildir Maildir mbox

In other multi level mailbox formats, INBOX is treated as a special case.

Maildir++

• Maildir++ defines the mail directory itself as INBOX. Any subdirectories inside starting with a single dot '.', and containing the file maildirfolder are interpreted as a Maildir++ submailbox.

• A Maildir is by Dan J. Bernstein's definition identified by a directory that contains the subdirectories cur, new and tmp and nothing else.

• The Maildir++ definition follows naturally from Maildir++ being an extension to Dan J. Bernstein's Maildir format. However, although the directory ~/Maildir/ itself is a standard representation of INBOX for Maildir clients, it is not standard for other mailbox formats. With Maildir++, your mailboxes and INBOX in particular must be a Maildir.

mbox

• When using the mbox storage format, the user's INBOX is typically stored at /var/spool/mail/<username>.
• Using this format, the mail depository client must both have the path to the user's INBOX and the path to the user's local mailbox depository, typically mail/.

Note that although IMAPdir has no restrictions with regards to mailbox names, the protocol that uses IMAPdir might. For example, IMAP servers will require the mailbox INBOX to be present.

---

Last updated on 2003-03-20.

Please direct comments to IMAPdir or this document to the Binc IMAP mailing list. Remember to search the archives first.