a utility to watch mailstores for changes and initiate mailbox syncs


mswatch is a command line unix program that keeps two mailboxes synchronized more efficiently and with shorter delays than periodically synchronizing the two mailboxes.

mswatch watches mailboxes to know when to initiate mailbox syncs. Using mswatch, your mail synchronization program can be called on demand instead of through polling, resulting in prompter mail delivery and lower bandwidth usage and server load.

mswatch is designed to work in conjunction with your mailbox synchronization program; e.g., mbsync or OfflineIMAP. mswatch monitors mailstores for changes by running itself on both the client and server (shell access to each is required) and currently supports watching Linux-hosted Maildirs, including Maildir++ folders. mswatch is licensed under the GNU GPL. Future support for additional mailbox formats, especially for mbox, is planned.




Why mswatch

Keeping a set of mailboxes on multiple computers means keeping the copies synchronized (eg on one's desktop and laptop or on a personal computer that cannot be reached while on the road and an always-reachable server). While the IMAP protocol is designed to support this and is widely used, IMAP clients can only detect mailbox changes by querying the server. Thus clients generally either sync when the user requests or sync periodically. However, because each mailbox sync uses server and network resources and because users often have a number of mailboxes, many of which receive mail infrequently, one must compromise between prompt message delivery and low server and network resource usage. Typical practice is to sync only when the user requests or to sync periodically with 5-10 minute frequencies. Nonetheless, it is often helpful for users to see new mail fairly soon after its arrival (eg notifications, group meeting changes, or active conversation threads).

mswatch addresses this speed of delivery vs resource usage tradeoff using interrupt-based instead of polling behavior to detect mailbox changes. mswatch asks each of the two mailstores to send mailbox change notifications; when mswatch receives a notification it in turn invokes the user's mailbox synchronization program for the changed mailbox. Thus, idle mailboxes do not use active resources and prompt mailbox synchronization is efficient.

Why mswatch Over Other Interrupt-based Approaches

While the above explains why one might want interrupt- instead of polling-based mailbox syncing, why use mswatch instead of another interrupt-based approach? Other known approaches and their limitations:

How mswatch Works

mswatch watches two sets of mailboxes for changes; when a change is detected mswatch invokes the user's mail synchronizer for the changed mailbox(es).


Each set of mailboxes (a "mailstore" in mswatch terminology) is watched through an external program which watches for changes to its mailstore and prints the name of a mailbox when the box is changed. Through this interface mswatch can watch local or remote (using ssh) mailstores. mswatch currently includes the program watch_maildirs to watch Linux hosted Maildirs. Programs to watch other mailstore types or support more platforms are most welcome! (If you are open to helping to test watch_mboxes, please email the mswatch list.)

mswatch reads and coalesces the mailbox names from each of the two mailstores. Following a short delay after a mailbox change (to allow multiple mailboxes to be synced with the same synchronization connection) mswatch invokes the mailbox synchronization program with the names of the changed mailboxes. mswatch was developed with mbsync in mind, but any mail synchronizer that implements the mailbox synchronizer interface can be invoked.

mswatch is designed to robustly interact with other programs and with networks:


watch_maildirs watches a Maildir-based mailstore for and reports changes; Maildir and Maildir folders (Maildir++) are supported. watch_maildirs uses Linux's inotify (2.6.13+) or dnotify (2.4.19+) interfaces to watch the Maildirs for mailbox changes.


inputkill is a small program that promptly kills a remote mailstore watcher when its connection to mswatch's dies; without it remote mailstore watchers would only exit much later, running needlessly. inputkill monitors its standard input; when stdin is closed, inputkill kills its child process and exits.


socketwatch monitors mail synchronization programs to detect and recover from program freezes while synchronizing – for example, we have seen deadlocks in interactions with SSL libraries and while IMAP clients wait for handshakes. Without socketwatch, such deadlocks can hang the mail synchronization program indefinitely. With socketwatch, they are reduced to increasing the run-time of the synchronization.


Because mswatch abstracts mail changes and synchronization to the mailbox (instead of message) level and because mail watcher communication is one-way, extra mailbox syncs occur. While it would be great to avoid this extra work, it is in the noise compared to the number of empty syncs that polling accumulates.

For example, the case of new mail delivered to the mail server's INBOX:

  1. mswatch detects the changed server INBOX
  2. mswatch invokes the mail syncer for INBOX, which adds the mail to the local INBOX
  3. mswatch detects the changed local INBOX
  4. mswatch invokes the mail syncer for INBOX, which detects no changes

Thus two syncs occur in this case instead of the single necessary sync.




Chris Frost Logo