4.2 - The Message Store

The Message Store (MS) represents the mechanism by which Mailismus defines and accesses mailboxes, for delivering email messages to local users (the final leg of any message's journey) and subsequently retrieving them on behalf of their email clients (Outlook, Thunderbird, etc) via POP3 or IMAP.

4.2.1 - Configuration

The top-level config block looks as follows:

<message_store class="...">

This specifies the MS implementation, and the default value if absent is the MaildirStore class illustrated in section § below.
The Maildir MS is the sole implementation provided as part of Mailismus, although as we shall see later, you may also define your own custom MS for delivery purposes (but not for retrieval).

The remaining config settings are implementation-specific.

4.2.2 - MS Types - Maildir-MS

The Maildir MS is an MS implementation that provides mailboxes based on the popular Maildir mail storage format.
It is a de facto standard, and the nearest it has to a specification remains Daniel Bernstein's original document, but as an end user, all you need to know about it is that you can access the mailboxes using any third-party mail reader, POP server or IMAP server that claims to be Maildir compatible (which in the Unix world at least, is lots of them).

<message_store class="com.grey.mailismus.ms.maildir.MaildirStore">

These fields collectively specify the path to each user's Maildir storage area.
userpath specifies the path to the users' home directory (or if virtual users, the path to the directories representing virtual users) and defaults to %DIRVAR%/ms.
mailpath specifies the relative path to the Maildir directory from the user's home directory, and defaults to Maildir.
The net result of the above settings, is that the mailbox aread for a user account named user1 will be under %DIRVAR%/ms/user1/Maildir.

The illustrative config block above clearly refers to virtual users since no actual user home directories are ever likely to be under the Mailismus work area, but on a typical Unix system where home directories are under /home, you would have to set userpath=/home and omit or default the mailpath setting, thus yielding Maildir paths like /home/user1/Maildir.

Internet messages are transmitted in a special syntax known as the "dot-stuffed" format, and the dot-stuffing has to be reversed at some stage before messages are presented to the end-user.
This config setting controls where the "dot-stuffing" gets undone.
It defaults to No, which means the dot-stuffing will not be undone when new messages are delivered into the MS by the MTA.

The following matrix illustrates which Mailismus process has to do what conversion work, depending on this setting.
Note that in terms of the message flow, it is the MTA which stores incoming messages (which are dot-stuffed to begin with) in the user's drop folder, while the POP3 and IMAP servers subsequently retrieve the messages from the drop folder.

dotstuffing MTA POP3 Server IMAP Server
No No conversion No conversion Undo dot-stuffing
Yes Undo dot-stuffing Redo dot-stuffing No conversion

The Mailismus POP3 and IMAP servers are able to take note of this setting to decide what conversion work is required on their part, so as can be seen the default setting of No is highly recommended, as it is optimal if the POP3 server is in play, and neutral if not (assuming an IMAP server is being used in its stead).
*** WARNING ***
The above analysis only applies if Mailismus is the only process being used to deliver or pick up the new messages.
If any other agent is adding/removing messages in the drop folder, then no optimisation is possible and the dotstuffing setting must be Yes, so that messages are always in the expected vanilla format for their current status.

This setting is No by default, but setting it to Yes permits some minor optimisations in the Mailismus MS-retrievel tasks (the IMAP and POP3 servers).
You can set it to Yes if you know that the Mailismus MTA is the only actor delivering new messages into the MS.

These settings allow you to vary the two special characters which are used in the filenames of Maildir messages, as the defaults (illustrated above) may cause difficulties on some non-Unix platforms.
In fact filename_colon defaults to + (plus sign) on Windows, so you shouldn't have to override these settings on Windows either.
You can enter the character as a decimal numeric value, by preceding it with / (forward slash)

4.2.3 - Custom MS

You may define your own custom implementation for the MS, which allows you to intercept message delivery and store received SMTP messages in your own store (eg. a database, or maybe even a bridging service that forwards emails in another medium, such as SMS texts).
Once messages have been delivered into a custom MS, message retrieval is entirely up to you. The message-access services provided as part of Mailismus (IMAP and POP3) will not interoperate with a custom MS.

A custom MS must implement the com.grey.mailismus.ms.MessageStore interface and the mailismus.xml config file would then specify its full classname in the message_store class attribute, as illustrated in section §4.2.1 above.

The JAR(s) which implement your custom code will need to be specified in the dependjars setting of the naf.xml config file (see NAF Programmer's Guide, section §2).

See the NAF Programmer's Guide and its open-source code for more info on the data types referred to here.