Merge pull request #228 from ddddavidmartin/extend_email_handling

Set email inbox in config file, fetch email at consumer startup and bring documentation up to date

docs/consumption.rst

@@ -121,18 +121,21 @@ So, with all that in mind, here's what you do to get it running:
 
 1. Setup a new email account somewhere, or if you're feeling daring, create a
    folder in an existing email box and note the path to that folder.
-2. In ``settings.py`` set all of the appropriate values in ``MAIL_CONSUMPTION``.
+2. In ``/etc/paperless.conf`` set all of the appropriate values in
+   ``PATHS AND FOLDERS`` and ``SECURITY``.
    If you decided to use a subfolder of an existing account, then make sure you
-   set ``INBOX`` accordingly here.  You also have to set the
+   set ``PAPERLESS_CONSUME_MAIL_INBOX`` accordingly here.  You also have to set
-   ``UPLOAD_SHARED_SECRET`` to something you can remember 'cause you'll have to
+   the ``PAPERLESS_SHARED_SECRET`` to something you can remember 'cause you'll
-   include that in every email you send.
+   have to include that in every email you send.
 3. Restart the :ref:`consumer <utilities-consumer>`.  The consumer will check
-   the configured email account every 10 minutes for something new and pull down
+   the configured email account at startup and from then on every 10 minutes
-   whatever it finds.
+   for something new and pulls down whatever it finds.
 4. Send yourself an email!  Note that the subject is treated as the file name,
    so if you set the subject to ``Correspondent - Title - tag,tag,tag``, you'll
    get what you expect.  Also, you must include the aforementioned secret
    string in every email so the fetcher knows that it's safe to import.
+   Note that Paperless only allows the email title to consist of safe characters
+   to be imported. These consist of alpha-numeric characters and ``-_ ,.'``.
 5. After a few minutes, the consumer will poll your mailbox, pull down the
    message, and place the attachment in the consumption directory with the
    appropriate name.  A few minutes later, the consumer will import it like any

paperless.conf.example

@@ -37,6 +37,10 @@ PAPERLESS_CONSUME_MAIL_PORT=""
 PAPERLESS_CONSUME_MAIL_USER=""
 PAPERLESS_CONSUME_MAIL_PASS=""
 
+# Override the default IMAP inbox here. If not set Paperless defaults to
+# "INBOX".
+#PAPERLESS_CONSUME_MAIL_INBOX=""
+
 
 ###############################################################################
 ####                              Security                                 ####

src/documents/mail.py

@@ -219,7 +219,7 @@ class MailFetcher(Loggable):
         if not login[0] == "OK":
             raise MailFetcherError("Can't log into mail: {}".format(login[1]))
 
-        inbox = self._connection.select("INBOX")
+        inbox = self._connection.select(self._inbox)
         if not inbox[0] == "OK":
             raise MailFetcherError("Can't find the inbox: {}".format(inbox[1]))
 

src/documents/management/commands/document_consumer.py

@@ -28,6 +28,7 @@ class Command(BaseCommand):
 
         self.file_consumer = None
         self.mail_fetcher = None
+        self.first_iteration = True
 
         BaseCommand.__init__(self, *args, **kwargs)
 
@@ -66,6 +67,9 @@ class Command(BaseCommand):
         self.file_consumer.consume()
 
         # Occasionally fetch mail and store it to be consumed on the next loop
+        # We fetch email when we first start up so that it is not necessary to
+        # wait for 10 minutes after making changes to the config file.
         delta = self.mail_fetcher.last_checked + self.MAIL_DELTA
-        if delta < datetime.datetime.now():
+        if self.first_iteration or delta < datetime.datetime.now():
+            self.first_iteration = False
             self.mail_fetcher.pull()

src/paperless/settings.py

@@ -244,8 +244,10 @@ MAIL_CONSUMPTION = {
     "PORT": os.getenv("PAPERLESS_CONSUME_MAIL_PORT"),
     "USERNAME": os.getenv("PAPERLESS_CONSUME_MAIL_USER"),
     "PASSWORD": os.getenv("PAPERLESS_CONSUME_MAIL_PASS"),
-    "USE_SSL": os.getenv("PAPERLESS_CONSUME_MAIL_USE_SSL", "y").lower() == "y",  # If True, use SSL/TLS to connect
+    # If True, use SSL/TLS to connect
-    "INBOX": "INBOX"  # The name of the inbox on the server
+    "USE_SSL": os.getenv("PAPERLESS_CONSUME_MAIL_USE_SSL", "y").lower() == "y",
+    # The name of the inbox on the server
+    "INBOX": os.getenv("PAPERLESS_CONSUME_MAIL_INBOX", "INBOX")
 }
 
 # This is used to encrypt the original documents and decrypt them later when