{
    "mode": "man",
    "parameter": "maildir",
    "section": "5",
    "url": "https://www.chedong.com/phpMan.php/man/maildir/5/json",
    "generated": "2026-05-30T06:10:42Z",
    "synopsis": "$HOME/Maildir",
    "sections": {
        "NAME": {
            "content": "maildir - E-mail directory\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "$HOME/Maildir\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "A “Maildir” is a structured directory that holds E-mail messages. Maildirs were first\nimplemented by the Qmail mail server. Qmail's maildirs were a simple data structure, nothing\nmore than a single collection of E-mail messages. The Courier mail server builds upon Qmail's\nmaildirs to provide extended functionality, such as folders and quotas. This document\ndescribes the Courier mail server's extended maildirs, without explicitly identifying The\nCourier mail server-specific extensions. See maildir(5) in Qmail's documentation for the\noriginal definition of maildirs.\n\nTraditionally, E-mail folders were saved as plain text files, called “mboxes”. Mboxes have\nknown limitations. Only one application can use an mbox at the same time. Locking is required\nin order to allow simultaneous concurrent access by different applications. Locking is often\nproblematic, and not very reliable in network-based filesystem requirements. Some\nnetwork-based filesystems don't offer any reliable locking mechanism at all. Furthermore,\neven bulletproof locking won't prevent occasional mbox corruption. A process can be killed or\nterminated in the middle of updating an mbox. This will likely result in corruption, and a\nloss of most messages in the mbox.\n\nMaildirs allow multiple concurrent access by different applications. Maildirs do not require\nlocking. Multiple applications can update a maildir at the same time, without stepping on\neach other's feet.\n",
            "subsections": [
                {
                    "name": "Maildir contents",
                    "content": "A “maildir” is a directory that's created by maildirmake(1)[1]. Naturally, maildirs should\nnot have any group or world permissions, unless you want other people to read your mail. A\nmaildir contains three subdirectories: tmp, new, and cur. These three subdirectories comprise\nthe primary folder, where new mail is delivered by the system.\n\nFolders are additional subdirectories in the maildir whose names begin with a period: such as\n.Drafts or .Sent. Each folder itself contains the same three subdirectories, tmp, new, and\ncur, and an additional zero-length file named maildirfolder, whose purpose is to inform any\nmail delivery agent that it's really delivering to a folder, and that the mail delivery agent\nshould look in the parent directory for any maildir-related information.\n\nFolders are not physically nested. A folder subdirectory, such as .Sent does not itself\ncontain any subfolders. The main maildir contains a single, flat list of subfolders. These\nfolders are logically nested, and periods serve to separate folder hierarchies. For example,\n.Sent.2002 is considered to be a subfolder called “2002” which is a subfolder of “Sent”.\n"
                },
                {
                    "name": "Folder name encoding",
                    "content": "Folder names can contain any Unicode character, except for control characters. US-ASCII\ncharacters, U+0x0020 - U+0x007F, except for the period, forward-slash, and ampersand\ncharacters (U+0x002E, U+0x002F, and U+0x0026) represent themselves. The ampersand is\nrepresent by the two character sequence “&-”. The period, forward slash, and non US-ASCII\nUnicode characters are represented using the UTF-7 character set, and encoded with a\nmodified form of base64-encoding.\n\nThe “&” character starts the modified base64-encoded sequence; the sequence is terminated\nby the “-” character. The sequence of 16-bit Unicode characters is written in big-endian\norder, and encoded using the base64-encoding method described in section 5.2 of RFC\n1521[2], with the following modifications:\n\n•   The “=” padding character is omitted. When decoding, an incomplete 16-bit character\nis discarded.\n\n•   The comma character, “,” is used in place of the “/” character in the base64\nalphabet.\n\nFor example, the word “Resume” with both \"e\"s being the e-acute character, U+0x00e9, is\nencoded as “R&AOk-sum&AOk-” (so a folder of that name would be a maildir subdirectory\ncalled “.R&AOk-sum&AOk-”).\n"
                },
                {
                    "name": "Other maildir contents",
                    "content": "Software that uses maildirs may also create additional files besides the tmp, new, and\ncur subdirectories -- in the main maildir or a subfolder -- for its own purposes.\n"
                },
                {
                    "name": "Messages",
                    "content": "E-mail messages are stored in separate, individual files, one E-mail message per file. The\ntmp subdirectory temporarily stores E-mail messages that are in the process of being\ndelivered to this maildir.  tmp may also store other kinds of temporary files, as long as\nthey are created in the same way that message files are created in tmp. The new subdirectory\nstores messages that have been delivered to this maildir, but have not yet been seen by any\nmail application. The cur subdirectory stores messages that have already been seen by mail\napplications.\n"
                },
                {
                    "name": "Adding new mail to maildirs",
                    "content": "The following process delivers a new message to the maildir:\n\nA new unique filename is created using one of two possible forms: “time.MusecPpid.host”, or\n“time.MusecPpidunique.host”.  “time” and “usec” is the current system time, obtained from\ngettimeofday(2).  “pid” is the process number of the process that is delivering this message\nto the maildir.  “host” is the name of the machine where the mail is being delivered. In the\nevent that the same process creates multiple messages, a suffix unique to each message is\nappended to the process id; preferrably an underscore, followed by an increasing counter.\nThis applies whether messages created by a process are all added to the same, or different,\nmaildirs. This protocol allows multiple processes running on multiple machines on the same\nnetwork to simultaneously create new messages without stomping on each other.\n\nThe filename created in the previous step is checked for existence by executing the stat(2)\nsystem call. If stat(2) results in ANYTHING OTHER than the system error ENOENT, the process\nmust sleep for two seconds, then go back and create another unique filename. This is an extra\nstep to insure that each new message has a completely unique filename.\n\nOther applications that wish to use tmp for temporary storage should observe the same\nprotocol (but see READING MAIL FROM MAILDIRS below, because old files in tmp will be\neventually deleted).\n\nIf the stat(2) system call returned ENOENT, the process may proceed to create the file in the\ntmp subdirectory, and save the entire message in the new file. The message saved MUST NOT\nhave the “From” header that is used to mboxes. The message also MUST NOT have any “From”\nlines in the contents of the message prefixed by the “>” character.\n\nWhen saving the message, the number of bytes returned by the write(2) system call must be\nchecked, in order to make sure that the complete message has been written out.\n\nAfter the message is saved, the file descriptor is fstat(2)-ed. The file's device number,\ninode number, and the its byte size, are saved. The file is closed and is then immediately\nmoved/renamed into the new subdirectory. The name of the file in new should be\n“time.MusecPpidVdevIino.host,S=cnt”, or “time.MusecPpidVdevIinounique.host,S=cnt”.  “dev” is\nthe message's device number, “ino” is the message's inode number (from the previous fstat(2)\ncall); and “cnt” is the message's size, in bytes.\n\nThe “,S=cnt” part optimizes the Courier[3] mail server's maildir quota enhancement; it allows\nthe size of all the mail stored in the maildir to be added up without issuing the stat(2)\nsystem call for each individual message (this can be quite a performance drain with certain\nnetwork filesystems).\n\nREADING MAIL FROM MAILDIRS\nApplications that read mail from maildirs should do it in the following order:\n\nWhen opening a maildir or a maildir folder, read the tmp subdirectory and delete any files in\nthere that are at least 36 hours old.\n\nLook for new messages in the new subdirectory. Rename new/filename, as cur/filename:2,info.\nHere, info represents the state of the message, and it consists of zero or more boolean flags\nchosen from the following: “D” - this is a 'draft' message, “R” - this message has been\nreplied to, “S” - this message has been viewed (seen), “T” - this message has been marked to\nbe deleted (trashed), but is not yet removed (messages are removed from maildirs simply by\ndeleting their file), “F” - this message has been marked by the user, for some purpose. These\nflags must be stored in alphabetical order. New messages contain only the :2, suffix, with no\nflags, indicating that the messages were not seen, replied, marked, or deleted.\n\nMaildirs may have maximum size quotas defined, but these quotas are purely voluntary. If you\nneed to implement mandatory quotas, you should use any quota facilities provided by the\nunderlying filesystem that is used to store the maildirs. The maildir quota enhancement is\ndesigned to be used in certain situations where filesystem-based quotas cannot be used for\nsome reason. The implementation is designed to avoid the use of any locking. As such, at\ncertain times the calculated quota may be imprecise, and certain anomalous situations may\nresult in the maildir actually going over the stated quota. One such situation would be when\napplications create messages without updating the quota estimate for the maildir. Eventually\nit will be precisely recalculated, but wherever possible new messages should be created in\ncompliance with the voluntary quota protocol.\n\nThe voluntary quota protocol involves some additional procedures that must be followed when\ncreating or deleting messages within a given maildir or its subfolders. The\ndeliverquota(8)[4] command is a tiny application that delivers a single message to a maildir\nusing the voluntary quota protocol, and hopefully it can be used as a measure of last resort.\nAlternatively, applications can use the libmaildir.a library to handle all the low-level\ndirty details for them. The voluntary quota enhancement is described in the\nmaildirquota(7)[5] man page.\n"
                },
                {
                    "name": "Maildir Quotas",
                    "content": "This is a voluntary mechanism for enforcing \"loose\" quotas on the maximum sizes of maildirs.\nThis mechanism is enforced in software, and not by the operating system. Therefore it is only\neffective as long as the maildirs themselves are not directly accessible by their users,\nsince this mechanism is trivially disabled.\n\nIf possible, operating system-enforced quotas are preferrable. Where operating system quota\nenforcement is not available, or not possible, this voluntary quota enforcement mechanism\nmight be an acceptable compromise. Since it's enforced in software, all software that\nmodifies or accesses the maildirs is required to voluntary obey and enforce a quota. The\nvoluntary quota implementation is flexible enough to allow non quota-aware applications to\nalso access the maildirs, without any drastic consequences. There will be some non-drastic\nconsequences, though. Of course, non quota-aware applications will not enforce any defined\nquotas. Furthermore, this voluntary maildir quota mechanism works by estimating the current\nsize of the maildir, with periodic exact recalculation. Obviously non quota-aware maildir\napplications will not update the maildir size estimation, so the estimate will be thrown off\nfor some period of time, until the next recalculation.\n\nThis voluntary quota mechanism is designed to be a reasonable compromise between\neffectiveness, and performance. The entire purpose of using maildir-based mail storage is to\navoid any kind of locking, and to permit parallel access to mail by multiple applications. In\norder to compute the exact size of a maildir, the maildir must be locked somehow to prevent\nany modifications while its contents are added up. Obviously something like that defeats the\noriginal purpose of using maildirs, therefore the voluntary quota mechanism does not use\nlocking, and that's why the current recorded maildir size is always considered to be an\nestimate. Regular size recalculations will compensate for any occasional race conditions that\nresult in the estimate to be thrown off.\n\nA quota for an existing maildir is installed by running maildirmake with the -q option, and\nnaming an existing maildir. The -q option takes a parameter, quota, which is a\ncomma-separated list of quota specifications. A quota specification consists of a number\nfollowed by either 'S', indicating the maximum message size in bytes, or 'C', maximum number\nof messages. For example:\n\nmaildirmake -q 5000000S,1000C ./Maildir\n\nThis sets the quota to 5,000,000 bytes or 1000 messages, whichever comes first.\n\nmaildirmake -q 1000000S ./Maildir\n\nThis sets the quota to 1,000,000 bytes, without limiting the number of messages.\n\nA quota of an existing maildir can be changed by rerunning the maildirmake command with a new\n-q option. To delete a quota entirely, delete the Maildir/maildirsize file.\n"
                }
            ]
        },
        "SEE ALSO": {
            "content": "maildirmake(1)[1].\n",
            "subsections": []
        },
        "AUTHOR": {
            "content": "",
            "subsections": [
                {
                    "name": "Sam Varshavchik",
                    "content": "Author\n"
                }
            ]
        },
        "NOTES": {
            "content": "1. maildirmake(1)\nhttp://www.courier-mta.org/maildirmake.html\n\n2. RFC 1521\nhttp://www.rfc-editor.org/rfc/rfc1521.txt\n\n3. Courier\nhttp://www.courier-mta.org\n\n4. deliverquota(8)\nhttp://www.courier-mta.org/deliverquota.html\n\n5. maildirquota(7)\nhttp://www.courier-mta.org/maildirquota.html\n\n\n\nCourier Mail Server                          07/24/2017                                   MAILDIR(5)",
            "subsections": []
        }
    },
    "summary": "maildir - E-mail directory",
    "flags": [],
    "examples": [],
    "see_also": [
        {
            "name": "maildirmake",
            "section": "1",
            "url": "https://www.chedong.com/phpMan.php/man/maildirmake/1/json"
        }
    ]
}