Initial commit.

readme.rst

@@ -0,0 +1,56 @@
+Introduction
+~~~~~~~~~~~~
+
+How many times have you had to consume some sort of POP3 or IMAP mailbox for incoming content?  One too many times for me.
+
+This small Django application will allow you to specify IMAP or POP3 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).
+
+WARNING!  This app will delete any messages it can find in the inbox you specify-- please make sure you don't have anything important in there.
+
+URI Examples
+============
+
+Mailbox URIs are in the normal URI format::
+
+    protocol://username:password@domain
+
+IMAP Example: ``imap://username:password@server``
+
+POP3 Example: ``pop3://username:password@server``
+
+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, )
+
+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
+========
+
+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``).