From 8a73076427895a49472d5ea2bb6f5f918468128e Mon Sep 17 00:00:00 2001
From: Steeve <mo0ofier@gmail.com>
Date: Sun, 15 May 2016 21:05:11 +0200
Subject: [PATCH] add imaps STARTTLS support (#94)

* add imaps STARTTLS support using +tls

* documentation on STARTTLS
---
 django_mailbox/models.py          |  6 ++++++
 django_mailbox/transports/imap.py |  6 +++++-
 docs/topics/mailbox_types.rst     | 13 +++++++------
 3 files changed, 18 insertions(+), 7 deletions(-)

diff --git a/django_mailbox/models.py b/django_mailbox/models.py
index be359dc..8121486 100644
--- a/django_mailbox/models.py
+++ b/django_mailbox/models.py
@@ -144,6 +144,11 @@ class Mailbox(models.Model):
         """Returns whether or not this mailbox's connection uses SSL."""
         return '+ssl' in self._protocol_info.scheme.lower()
 
+    @property
+    def use_tls(self):
+        """Returns whether or not this mailbox's connection uses STARTTLS."""
+        return '+tls' in self._protocol_info.scheme.lower()
+
     @property
     def archive(self):
         """Returns (if specified) the folder to archive messages to."""
@@ -174,6 +179,7 @@ class Mailbox(models.Model):
                 self.location,
                 port=self.port if self.port else None,
                 ssl=self.use_ssl,
+                tls=self.use_tls,
                 archive=self.archive,
                 folder=self.folder
             )
diff --git a/django_mailbox/transports/imap.py b/django_mailbox/transports/imap.py
index 6f0f5d1..2c449c3 100644
--- a/django_mailbox/transports/imap.py
+++ b/django_mailbox/transports/imap.py
@@ -18,7 +18,8 @@ logger = logging.getLogger(__name__)
 
 class ImapTransport(EmailTransport):
     def __init__(
-        self, hostname, port=None, ssl=False, archive='', folder=None
+        self, hostname, port=None, ssl=False, tls=False,
+        archive='', folder=None,
     ):
         self.max_message_size = getattr(
             settings,
@@ -34,6 +35,7 @@ class ImapTransport(EmailTransport):
         self.port = port
         self.archive = archive
         self.folder = folder
+        self.tls = tls
         if ssl:
             self.transport = imaplib.IMAP4_SSL
             if not self.port:
@@ -45,6 +47,8 @@ class ImapTransport(EmailTransport):
 
     def connect(self, username, password):
         self.server = self.transport(self.hostname, self.port)
+        if self.tls:
+            self.server.starttls()
         typ, msg = self.server.login(username, password)
 
         if self.folder:
diff --git a/docs/topics/mailbox_types.rst b/docs/topics/mailbox_types.rst
index a1bfceb..4056eac 100644
--- a/docs/topics/mailbox_types.rst
+++ b/docs/topics/mailbox_types.rst
@@ -7,11 +7,11 @@ 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://``; additional configuration is also possible: see :ref:`pop3-and-imap-mailboxes` for details.
+  IMAP         ``imap://``      Can also specify SSL with ``imap+ssl://`` or STARTTLS with ``imap+tls``; additional configuration is also possible: see :ref:`pop3-and-imap-mailboxes` for details.
   Gmail IMAP   ``gmail+ssl://`` Uses OAuth authentication for  Gmail's IMAP transport.  See :ref:`gmail-oauth` for details.
   Maildir      ``maildir://``
   Mbox         ``mbox://``
@@ -19,7 +19,7 @@ POP3 and IMAP as well as local file-based mailboxes.
   MH           ``mh://``
   MMDF         ``mmdf://``
   Piped Mail   *empty*          See :ref:`receiving-mail-from-exim4-or-postfix`
-  ============ ================ =================================================================================================================================================================
+  ============ ================ ====================================================================================================================================================================
 
 
 .. warning::
@@ -42,8 +42,9 @@ Basic IMAP Example: ``imap://username:password@server``
 
 Basic POP3 Example: ``pop3://username:password@server``
 
-Most mailboxes these days are SSL-enabled; 
-if yours is, add ``+ssl`` to the protocol section of your URI.  
+Most mailboxes these days are SSL-enabled;
+if yours use plain SSL add ``+ssl`` to the protocol section of your URI,
+but for STARTTLS add ``+tls``.
 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).