How many times have you had to consume some sort of POP3, IMAP, or local mailbox for incoming content, or had to otherwise construct an application driven by e-mail? One too many times, I'm sure.
This small Django application will allow you to specify mailboxes that you would like consumed for incoming content; the e-mail will be stored, and you can process it at will (or, if you're in a hurry, by subscribing to a signal).
Most mailboxes these days are SSL-enabled; if yours is, add ``+ssl`` to your URI. Also, if your username or password include any non-ascii characters, they should be URL-encoded (for example, if your username includes an ``@``, it should be changed to ``%40`` in your URI).
If you have an account named ``youremailaddress@gmail.com`` with a password of ``1234`` on GMail (which I happen to know uses the POP3 server of 'pop.gmail.com' and requires SSL), you would enter the following as your URI::
If you happen to want to consume a file-based mailbox like an Maildir, Mbox, Babyl, MH, or MMDF mailbox, you can use this too by entering the appropriate 'protocol' in the URI. If you had a maildir, for example, at ``/var/mail/``, you would enter a URI like::
You can easily consume incoming mail by running the management command named ``getmail`` (optionally with an argument of the name of the mailbox you'd like to get the mail for).::
Django Mailbox's ``processincomingmessage`` management command accepts, via ``stdin``, incoming messages. You can configure Postfix or Exim4 to pipe incoming mail to this management command to import messages directly without polling. You need not configure mailbox settings when piping-in messages, mailbox entries will be automatically created matching the e-mail address to which incoming messages are sent.
Make sure that the e-mail addresses you would like handled by Django Mailbox are not handled by another router; you may need to disable some existing routers.
Change the contents of ``local_parts`` to match a colon-delimited list of usernames for which you would like to receive mail for. For example, if one of the e-mail addresses targeted at this machine is ``jane@example.com``, the contents of ``local_parts`` would be, simply ``jane``.
Like your router configuration, transport configuration should be altered to match your environment. First, modify the ``command`` setting such that it points at the proper python executable (if you're using a virtual environment, you'll want to direct that at the python executable in your virtual environment) and project ``manage.py`` script. Additionally, you'll need to set ``user`` and ``group`` such that they match a reasonable user and group (on Ubuntu, ``www-data`` suffices for both).
Although I have not personally tried using Postfix for this, Postfix is capable of delivering new mail to a script using ``pipe``. Please consult the `Postfix documentation for pipe here <http://www.postfix.org/pipe.8.html>`_. You may want to consult the above Exim4 configuration for tips.
Subscribing to the incoming mail signal
=======================================
To subscribe to the incoming mail signal, following this lead::
from django_mailbox.signals import message_received
from django.dispatch import receiver
@receiver(message_received)
def dance_jig(sender, message, **args):
print "I just recieved a message titled %s from a mailbox named %s" % (message.subject, message.mailbox.name, )
You can disable mailbox information from being listed in the Django admin by adding a setting named ``DJANGO_MAILBOX_ADMIN_ENABLED`` indicating your preference toward whether or not the models appear in the admin (defaulting to ``True``).
