Added email archiving option to IMAP transport

django_mailbox/models.py

@@ -146,6 +146,10 @@ class Mailbox(models.Model):
     def use_ssl(self):
         return '+ssl' in self._protocol_info.scheme.lower()
 
+    @property
+    def archive(self):
+        return self._protocol_info.query
+
     def get_connection(self):
         if not self.uri:
             return None
@@ -153,7 +157,8 @@ class Mailbox(models.Model):
             conn = ImapTransport(
                 self.location,
                 port=self.port if self.port else None,
-                ssl=self.use_ssl
+                ssl=self.use_ssl,
+                archive=self.archive
             )
             conn.connect(self.username, self.password)
         elif self.type == 'pop3':

django_mailbox/tests/test_transports.py

@@ -10,10 +10,12 @@ class TestImapTransport(EmailMessageTestCase):
         self.arbitrary_hostname = 'one.two.three'
         self.arbitrary_port = 100
         self.ssl = False
+        self.archive = 'Archive'
         self.transport = ImapTransport(
             self.arbitrary_hostname,
             self.arbitrary_port,
-            self.ssl
+            self.ssl,
+            self.archive
         )
         self.transport.server = None
         super(TestImapTransport, self).setUp()
@@ -36,7 +38,18 @@ class TestImapTransport(EmailMessageTestCase):
                     ')',
                 ]
             )
-
+            server.list.return_value = (
+                'OK',
+                [
+                    '(\\HasNoChildren) "/" "Archive"'
+                ]
+            )
+            server.copy.return_value = (
+                'OK',
+                [
+                    '[COPYUID 1 2 2] (Success)'
+                ]
+            )
             actual_messages = list(self.transport.get_message())
 
         self.assertEqual(len(actual_messages), 1)

django_mailbox/transports/imap.py

@@ -4,9 +4,10 @@ from .base import EmailTransport, MessageParseError
 
 
 class ImapTransport(EmailTransport):
-    def __init__(self, hostname, port=None, ssl=False):
+    def __init__(self, hostname, port=None, ssl=False, archive=''):
         self.hostname = hostname
         self.port = port
+        self.archive = archive
         if ssl:
             self.transport = IMAP4_SSL
             if not self.port:
@@ -27,6 +28,11 @@ class ImapTransport(EmailTransport):
         if not inbox[0]:
             return
 
+        if self.archive:
+            typ, folders = self.server.list(pattern=self.archive)
+            if folders[0] == None:
+                self.archive = False  
+
         for key in inbox[0].split():
             try:
                 typ, msg_contents = self.server.fetch(key, '(RFC822)')
@@ -34,6 +40,10 @@ class ImapTransport(EmailTransport):
                 yield message
             except MessageParseError:
                 continue
+
+            if self.archive:
+                self.server.copy(key, self.archive)
+
             self.server.store(key, "+FLAGS", "\\Deleted")
         self.server.expunge()
         return

docs/topics/mailbox_types.rst

@@ -7,24 +7,25 @@ POP3 and IMAP as well as local file-based mailboxes.
 
 .. table:: 'Protocol' Options
 
-  ============ ============== ===============================================
+  ============ ============== ===============================================================
   Mailbox Type 'Protocol'://  Notes
-  ============ ============== ===============================================
+  ============ ============== ===============================================================
   POP3         ``pop3://``    Can also specify SSL with ``pop3+ssl://``
-  IMAP         ``imap://``    Can also specify SSL with ``imap+ssl://``
+  IMAP         ``imap://``    Can also specify SSL and archive with ``imap+ssl://?myarchive``
   Maildir      ``maildir://``
   Mbox         ``mbox://``
   Babyl        ``babyl://``
   MH           ``mh://``
   MMDF         ``mmdf://``
   Piped Mail   *empty*        See :ref:`receiving-mail-from-exim4-or-postfix`
-  ============ ============== ===============================================
+  ============ ============== ===============================================================
 
 .. warning::
 
-   This will delete any messages it can find in the inbox you specify; 
+   This will delete or move any messages it can find in the inbox you specify;
    do not use an e-mail inbox that you would like to share between
-   applications.
+   applications. For the IMAP protocol you can specify an archive folder where
+   emails are moved to.
 
 
 POP3 and IMAP Mailboxes
@@ -44,11 +45,17 @@ 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 uses a POP3 server of 'pop.gmail.com' and requires
-SSL, you would enter the following as your URI::
+If you are using an IMAP Mailbox, you can archive all messages before they
+are deleted from the inbox. To archive emails, add the archive folder
+name as a queryparemeter to the uri (for example, if your mailbox has a
+folder called myarchive, add ``?myarchive`` to the uri).
 
-    pop3+ssl://youremailaddress%40gmail.com:1234@pop.gmail.com
+If you have an account named ``youremailaddress@gmail.com`` with a password
+of ``1234`` on GMail, which uses a IMAP server of 'imap.gmail.com', requires
+SSL and you want to archive all emails, you would enter the following as 
+your URI::
+
+    pop3+ssl://youremailaddress%40gmail.com:1234@pop.gmail.com?[GMAIL]/All Mail
 
 
 Local File-based Mailboxes