mailsync is mainly suitable for the following three tasks:

mailsync distinguishes between the mailbox itself (the store) and the connection between two mailboxes (the channel. The definitions of the stores and channels are stored in ~/.mailsync. The following paragraphs explain a number of store examples.

A simple definition might appear as follows:

store saved-messages { 
   pat Mail/saved-messages
prefix  Mail/
}

Mail/ is a subdirectory of the user's home directory that contains e-mail folders, including the folder saved-messages. If mailsync is started with mailsync -m saved-messages an index of all messages is listed in saved-messages. If the following definition is made

store localdir { 
pat     Mail/* 
prefix  Mail/ 
} 

the command mailsync -m localdir causes all messages stored under Mail/ to be listed. In contrast, the command mailsync localdir lists the folder names. The specifications of a store on an IMAP server appear as follows:

store imapinbox {
server {mail.edu.harvard.com/user=gulliver}
ref    {mail.edu.harvard.com}
pat    INBOX 
}

The above example merely addresses the main folder on the IMAP server. A store for the subfolders would appear as follows:

store imapdir {
server {mail.edu.harvard.com/user=gulliver}
ref {mail.edu.harvard.com}
pat INBOX.*
prefix  INBOX.
}

If the IMAP server supports encrypted connections, the server specification should be changed to

server {mail.edu.harvard.com/ssl/user=gulliver}

or, if the server certificate is not known, to

server {mail.edu.harvard.com/ssl/novalidate-cert/user=gulliver}

The prefix is explained later.

Now the folders under Mail/ should be connected to the subdirectories on the IMAP server:

channel folder localdir imapdir {
msinfo .mailsync.info
} 

mailsync uses the msinfo file to keep track of the messages that have already been synchronized.

The command mailsync folder does the following:

Accordingly, the folder INBOX.sent-mail on the IMAP server is synchronized with the local folder Mail/sent-mail (provided the definitions explained above exist). The synchronization between the individual folder is performed as follows:

To know in advance which messages will be transmitted and which will be deleted during a synchronization, start mailsync with a channel and a store with mailsync folder localdir. This command produces a list of all messages that are new on the local host as well as a list of all messages that would be deleted on the IMAP side during a synchronization. Similarly, the command mailsync folder imapdir produces a list of all messages that are new on the IMAP side and a list of all messages that would be deleted on the local host during a synchronization.

In the event of a data loss, the safest method is to delete the relevant channel log file msinfo. Accordingly, all messages that only exist on one side are viewed as new and are therefore transmitted during the next synchronization.

Only messages with a message ID are included in the synchronization. Messages lacking a message ID are simply ignored, which means they are neither transmitted nor deleted. A missing message ID is usually caused by faulty programs when sending or writing a message.

On certain IMAP servers, the main folder is addressed with INBOX and subfolders are addressed with a randomly selected name (in contrast to INBOX and INBOX.name). Therefore, for such IMAP servers, it is not possible to specify a pattern exclusively for the subfolders.

After the successful transmission of messages to an IMAP server, the mailbox drivers (c-client) used by mailsync set a special status flag. For this reason, some e-mail programs, like mutt, are not able to recognize these messages as new. The setting of this special status flag can be disabled with the option -n.

The README in /usr/share/doc/packages/mailsync/, which is included in mailsync, provides additional information. In this connection, RFC 2076 “Common Internet Message Headers” is of special interest.