Mail Monitoring
===============

Rattail has a basic "Mail Monitoring" (mailmon) service which can
watch an IMAP folder, and perform actions on any messages which
appear.  

Note that one of those actions, presumably the last, should be to
*move* the message into a different IMAP folder, or perhaps delete it
outright.  This is to avoid re-processing the same message over and
over.  The IMAP folder being watched is essentially treated as a
"queue" and everything in it will be processed.

Example config for this looks something like (in ``mailmon.conf``):

.. code-block:: ini

   [rattail.mailmon]
   monitor = myfolder

   myfolder.imap.server = mail.example.com
   myfolder.imap.username = myuser
   myfolder.imap.password = mypass
   myfolder.imap.folder = INBOX.Incoming-Messages
   myfolder.actions = download, move
   myfolder.action.download.func = rattail.mailmon.actions:download_message
   myfolder.action.download.args = /srv/envs/poser/app/work/mailmon/myfolder
   myfolder.action.download.kwarg.locking = true
   myfolder.action.move.func = rattail.mailmon.actions:move_message
   myfolder.action.move.args = INBOX.Processed-Messages

In the above example we are watching the "Incoming-Messages" folder,
which is a subfolder of the INBOX itself.  Any messages which appear
there will be downloaded to local file system, and then moved to the
"Processed-Messages" IMAP folder on the server.

Running the command is usually done via supervisor (so as to make it
behave as a proper service), but the command line itself looks like:

.. code-block:: sh

   cd /srv/envs/poser
   sudo -u rattail bin/rattail -c app/mailmon.conf mailmon start