A "Maildir" is a structured directory that holds E-mail messages. Maildirs were first implemented by the Qmail mail server. Qmail's maildirs were a simple data structure, nothing more than a single collection of E-mail messages. Courier builds upon Qmail's maildirs to provide extended functionality, such as folders and quotas. This document describes Courier's extended maildirs, without explicitly identifying Courier-specific extensions. See maildir(5) in Qmail's documentation for the original definition of maildirs.
Traditionally, E-mail folders were saved as plain text files, called "mboxes". Mboxes have known limitations. Only one application can use an mbox at the same time. Locking is required in order to allow simultaneous concurrent access by different applications. Locking is often problematic, and not very reliable in network-based filesystem requirements. Some network-based filesystems don't offer any reliable locking mechanism at all. Furthermore, even bulletproof locking won't prevent occasional mbox corruption. A process can be killed or terminated in the middle of updating an mbox. This will likely result in corruption, and a loss of most messages in the mbox.
Maildirs allow multiple concurrent access by different applications. Maildirs do not require locking. Multiple applications can update a maildir at the same time, without stepping on each other's feet.
A "maildir" is a directory that's created by maildirmake(1). Naturally, maildirs should not have any group or world permissions, unless you want other people to read your mail. A maildir contains three subdirectories: tmp, new, and cur. These three subdirectories comprise the primary folder, where new mail is delivered by the system.
Folders are additional subdirectories in the maildir whose names begin with a period: such as .Drafts or .Sent. Each folder itself contains the same three subdirectories, tmp, new, and cur, and an additional zero-length file named maildirfolder, whose purpose is to inform any mail delivery agent that it's really delivering to a folder, and that the mail delivery agent should look in the parent directory for any maildir-related information.
Folders are not physically nested. A folder subdirectory, such as .Sent does not itself contain any subfolders. The main maildir contains a single, flat list of subfolders. These folders are logically nested, and periods serve to separate folder hierarchies. For example, .Sent.2002 is considered to be a subfolder called "2002" which is a subfolder of "Sent".
Folder names can contain any Unicode character, except for control characters. US-ASCII characters, U+0x0020 - U+0x007F, except for the period, forward-slash, and ampersand characters (U+0x002E, U+0x002F, and U+0x0026) represent themselves. The ampersand is represent by the two character sequence "&-". The period, forward slash, and non US-ASCII Unicode characters are represented using the UTF-7 character set, and encoded with a modified form of base64-encoding.
The "&" character starts the modified base64-encoded sequence; the sequence is terminated by the "-" character. The sequence of 16-bit Unicode characters is written in big-endian order, and encoded using the base64-encoding method described in section 5.2 of RFC 1521, with the following modifications:
The "=" padding character is omitted. When decoding, an incomplete 16-bit character is discarded.
The comma character, "," is used in place of the "/" character in the base64 alphabet.
For example, the word "Resume" with both "e"s being the e-acute character, U+0x00e9, is encoded as "R&AOk-sum&AOk-" (so a folder of that name would be a maildir subdirectory called ".R&AOk-sum&AOk-").
E-mail messages are stored in separate, individual files, one E-mail message per file. The tmp subdirectory temporarily stores E-mail messages that are in the process of being delivered to this maildir. tmp may also store other kinds of temporary files, as long as they are created in the same way that message files are created in tmp. The new subdirectory stores messages that have been delivered to this maildir, but have not yet been seen by any mail application. The cur subdirectory stores messages that have already been seen by mail applications.
The following process delivers a new message to the maildir:
A new unique filename is created using one of two possible forms: "time.MusecPpid.host", or "time.MusecPpid_unique.host". "time" and "usec" is the current system time, obtained from gettimeofday(2). "pid" is the process number of the process that is delivering this message to the maildir. "host" is the name of the machine where the mail is being delivered. In the event that the same process creates multiple messages, a suffix unique to each message is appended to the process id; preferrably an underscore, followed by an increasing counter. This applies whether messages created by a process are all added to the same, or different, maildirs. This protocol allows multiple processes running on multiple machines on the same network to simultaneously create new messages without stomping on each other.
The filename created in the previous step is checked for existence by executing the stat(2) system call. If stat(2) results in ANYTHING OTHER than the system error ENOENT, the process must sleep for two seconds, then go back and create another unique filename. This is an extra step to insure that each new message has a completely unique filename.
Other applications that wish to use tmp for temporary storage should observe the same protocol (but see READING MAIL FROM MAILDIRS below, because old files in tmp will be eventually deleted).
If the stat(2) system call returned ENOENT, the process may proceed to create the file in the tmp subdirectory, and save the entire message in the new file. The message saved MUST NOT have the "From_" header that is used to mboxes. The message also MUST NOT have any "From_" lines in the contents of the message prefixed by the ">" character.
When saving the message, the number of bytes returned by the write(2) system call must be checked, in order to make sure that the complete message has been ./usr/share/maildrop/html/deliverquota.html 0000644 0000000 0000000 00000011053 11330353773 017776 0 ustar root root
deliverquota delivers mail to a maildir taking into account any software-imposed quota on the maildir. This manually-enforced quota mechanism is described in the maildirquota(7) and maildirmake(1) manual pages. Instead of setting up your mail server to deliver the message directly to a maildir, configure the mail server to run the deliverquota program in order to deliver the message, and specify the location of the maildir as the argument to deliverquota.
The second argument to deliverquota is optional. If present, quota specifies a new quota setting for this maildir. Specifying quota is equivalent to running maildirmake(1) with the -q option. The second argument to deliverquota is considered obsolete, and may be removed in the future.
deliverquota reads the message from standard input and delivers it to maildir. maildir may specify a path directly to a maildir folder, not the main maildir (as long as the folder was created by the maildirmake(1) command.
The -c option automatically creates the maildir, and all missing parent subdirectories (as 'mkdir -p'). This option should be used with caution.
The -w N option places a warning message into the maildir if the maildir has a quota setting, and after the message was successfully delivered the maildir was at least N percent full. The warning message is copied verbatim from /etc/quotawarnmsg with the addition of the "Date:" and "Message-Id:" headers. The warning is repeated every 24 hours (at least), until the maildir drops below N percent full.
deliverquota delivers the message to the maildir and terminates with exit code 0 if the message can be delivered without going over quota.
If the maildir is over its specified quota, deliverquota terminates with exit code 77 (EX_NOPERM).
A "Maildir" is a structured directory that holds E-mail messages. Maildirs were first implemented by the Qmail mail server. Qmail's maildirs were a simple data structure, nothing more than a single collection of E-mail messages. Courier builds upon Qmail's maildirs to provide extended functionality, such as folders and quotas. This document describes Courier's extended maildirs, without explicitly identifying Courier-specific extensions. See maildir(5) in Qmail's documentation for the original definition of maildirs.
Traditionally, E-mail folders were saved as plain text files, called "mboxes". Mboxes have known limitations. Only one application can use an mbox at the same time. Locking is required in order to allow simultaneous concurrent access by different applications. Locking is often problematic, and not very reliable i