Notes about various maildir formats

ben / tech / maildir

Notes about various maildir formats

I've encountered various extensions to the base maildir format described in (DJB).

This page summarises those extensions, but probably doesn't make much sense without reading some other maildir description (such as (DJB)).

I'm interested in hearing about maildir behaviour/formats that are not described below - please send updates to benc@hawaga.org.uk.

Maildir messages appear under some root directory, such as ~/Maildir.

A maildir filename looks roughly like:
[ folder '/' ] sub '/' uniq [ ',' attribs ] ':2,' flags [ ',' dovecotfields ]
where [] symbolises optional fields.

folder is a subdirectory beginning with '.' (so, for example, .personal)

(COURIER) specifies that subfolders are encoded in a single filename, separated by dots.

(COURIER) specifies a way of encoding unicode characters using a base-64 encoding using the & symbol. So that symbol should probably be avoided in folder names in general.

sub may be 'new' or 'cur' (or 'tmp' while preparing a new message). (DJB). It is implied in (DJB) that (':2,' flags) should not be present in a message in 'new', and that (':2,' flags) should be added at the point that a maildir reader moves the message from 'new' to 'cur'.

In (DJB), uniq is an opaque field. However, lots of software parses information out of the field, and otherwise expects it to be in a certain format.

(DBJ) says that A unique name can be anything that doesn't contain a colon (or slash) and doesn't start with a dot (at least if you are reading messages, not writing them). The presence of attribs means that the unique name should also not contain a comma. For writing unique names, (DJB) specifies a way of creating a unique name that is followed by most software that I've encountered, except for 2005-era procmail; and another historical format.

(COURIER) specifies a similar way of generating unique names, but with fewer generation options than (DJB).

attribs seem to take the form

  letter '=' value
I've seen two different letters used here:

In my use, I've only seen flags used as described in (DJB). Briefly, from that doc:

Flag "P" (passed): the user has resent/forwarded/bounced this message to someone else.
Flag "R" (replied): the user has replied to this message.
Flag "S" (seen): the user has viewed this message, though perhaps he didn't read all the way through it.
Flag "T" (trashed): the user has moved this message to the trash; the trash will be emptied by a later user action.
Flag "D" (draft): the user considers this message a draft; toggled at user discretion.
Flag "F" (flagged): user-defined flag; toggled at user discretion.

(DOVECOT) uses all 26 lowercase flag letters to represent IMAP keywords.

dovecotfields is slightly strange in that it is defined in (DOVECOT) and then never used for anything, so perhaps might as well never exist in the first place?

Example maildir filenames

These are actual maildir filenames written by various pieces of software over the last 5 years:

From procmail, november 2005:

_-BF,okOjDB.mundungus:2,S
One version of the pine maildir driver did not recognise this as a valid maildir filename, and so did not see messages with this format of name. The unique ID does not look like that described in (DJB).

From courier imap:

1136850601.M749735P15170V0E000002I00CB189A_2.piva.local,S=485:2,S
1136899138.M533326P308V0E000002I00CB4AC9_0.piva.hawaga.org.uk,S=663:2,S

Maildir filenames after a 2009 vintage Alpine has touched them:

_-BF,okOjDB.mundungus,u=10:2,S
1138758896.M999686P28654V0E000002I00D02E74_0.piva.hawaga.org.uk,S=691,u=2931:2,S
Note the addition of the u= attribute.

Locking

Various extensions to maildir provide folder-wide locks. I haven't written about these here but they're detailed in the references.

References

(DJB) djb's original maildir description.
(MAILDIR++) Maildir++ in Courier-IMAP, which adds quotas and folders to maildir.
(ALPINEMAILDIR) maildir patch for alpine
(DOVECOT) DoveCot's implementation of maildir
(COURIER) Courier MTA