diff --git a/readme.rst b/readme.rst index 3b7a43d..9855045 100755 --- a/readme.rst +++ b/readme.rst @@ -26,8 +26,8 @@ You can either install from pip:: cd django-mailbox python setup.py install -Setting up your mailbox -======================= +Polling for mail in POP3/IMAP or a local mailbox +================================================ Django Mailbox supports both common internet mailboxes like POP3 and IMAP as well as local file-based mailboxes. @@ -71,6 +71,62 @@ If you happen to want to consume a file-based mailbox like an Maildir, Mbox, Bab Note that there is an additional ``/`` in the above URI after the protocol; this is important. +Getting incoming mail +--------------------- + +In your code +~~~~~~~~~~~~ + +Mailbox instances have a method named ``get_new_mail``; this method will gather new messages from the server. + +Using the Django Admin +~~~~~~~~~~~~~~~~~~~~~~ + +Check the box next to each of the mailboxes you'd like to fetch e-mail from, and select the 'Get new mail' option. + +Using a cron job +~~~~~~~~~~~~~~~~ + +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).:: + + python manage.py getmail + +Receiving mail directly from EXIM4 or Postfix via a pipe +======================================================== + +Django Mailbox's ``processincomingmessage`` management command accespts, via ``stdin``, incoming messages. You can configure Postfix or Exim4 to pipe incoming mail to this management command to import messages directly without polling. + +Receiving Mail from Exim4 +------------------------- + +You should add a new router configuration to your Exim4 configuration like:: + + django_mailbox: + debug_print = 'R: django_mailbox for $localpart@$domain' + driver = accept + domains = +local_domains + transport = send_to_django_mailbox + local_parts = emailusernameone : emailusernametwo + +You will want to make sure that the e-mail addresses you would like handled by Django Mailbox are not handled by another router, so you may need to disable some existing routers. Also, be sure to 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``. + +You should also add a new transport configuration to your Exim4 configuration:: + + send_to_django_mailbox: + driver = pipe + command = /path/to/your/environments/python /path/to/your/projects/manage.py processincomingmessage + user = www-data + group = www-data + return_path_add + delivery_date_add + +Like your router configuration, you will need to alter this transport configuration. First, you will want to modify the ``command`` setting such that it points at the proper python binary (if you're using a virtual environment, you'll want to direct that at the python binary 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). + +Receiving mail from Postfix +--------------------------- + +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 `_. You may want to consult the above Exim4 configuration for tips. + Subscribing to the incoming mail signal ======================================= @@ -83,25 +139,6 @@ To subscribe to the incoming mail signal, following this lead:: def dance_jig(sender, message, **args): print "I just recieved a message titled %s from a mailbox named %s" % (message.subject, message.mailbox.name, ) -Getting incoming mail -======================= - -In your code ------------- - -Mailbox instances have a method named ``get_new_mail``; this method will gather new messages from the server. - -Using the Django Admin ----------------------- - -Check the box next to each of the mailboxes you'd like to fetch e-mail from, and select the 'Get new mail' option. - -Using a cron job ----------------- - -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).:: - - python manage.py getmail Settings ======== diff --git a/scripts/router b/scripts/router deleted file mode 100644 index 3980d16..0000000 --- a/scripts/router +++ /dev/null @@ -1,6 +0,0 @@ -django_mailbox: - debug_print = 'R: django_mailbox for $localpart@$domain" - driver = accept - domains = +local_domains - transport = send_to_django_mailbox - local_parts = emailaddressusername : anotheremailaddressusername diff --git a/scripts/transport b/scripts/transport deleted file mode 100644 index 21a2d1a..0000000 --- a/scripts/transport +++ /dev/null @@ -1,8 +0,0 @@ - -send_to_django_mailbox: - driver = pipe - command = /path/to/python /path/to/manage.py processincomingmessage - user = www-data - group = www-data - return_path_add - delivery_date_add