diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..67ea2df --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,153 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + -rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/django-mailbox.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/django-mailbox.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/django-mailbox" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/django-mailbox" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..a234e8c --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,242 @@ +# -*- coding: utf-8 -*- +# +# django-mailbox documentation build configuration file, created by +# sphinx-quickstart on Tue Jan 22 20:29:12 2013. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.viewcode'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'django-mailbox' +copyright = u'2013, Adam Coddington' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '1.8.1' +# The full version, including alpha/beta/rc tags. +release = '1.8.1' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'django-mailboxdoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'django-mailbox.tex', u'django-mailbox Documentation', + u'Adam Coddington', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'django-mailbox', u'django-mailbox Documentation', + [u'Adam Coddington'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------------ + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'django-mailbox', u'django-mailbox Documentation', + u'Adam Coddington', 'django-mailbox', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..199c865 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,33 @@ +.. django-mailbox documentation master file, created by + sphinx-quickstart on Tue Jan 22 20:29:12 2013. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Django-mailbox +============== + +.. image:: https://travis-ci.org/latestrevision/django-mailbox.png?branch=master + +How many times have you had to consume some sort of POP3, IMAP, or local mailbox for incoming content, +or had to otherwise construct an application driven by e-mail? +One too many times, I'm sure. + +This small Django application will allow you to specify 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). + +Contents: + +.. toctree:: + :maxdepth: 2 + :glob: + + topics/* + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` + diff --git a/docs/topics/file_based.rst b/docs/topics/file_based.rst new file mode 100644 index 0000000..0820422 --- /dev/null +++ b/docs/topics/file_based.rst @@ -0,0 +1,13 @@ + +Local File-based Mailboxes +-------------------------- + +If you happen to want to consume a file-based mailbox like an Maildir, Mbox, Babyl, MH, or MMDF mailbox, +you can use this too by entering the appropriate 'protocol' in the URI. +If you had a maildir, for example, at ``/var/mail/``, you would enter a URI like:: + + maildir:///var/mail + +Note that there is an additional ``/`` in the above URI after the protocol; +this is important. + diff --git a/docs/topics/installation.rst b/docs/topics/installation.rst new file mode 100644 index 0000000..ce908b4 --- /dev/null +++ b/docs/topics/installation.rst @@ -0,0 +1,23 @@ + +Installation +============ + +You can either install from pip:: + + pip install django-mailbox + +*or* checkout and install the source from the `bitbucket repository `_:: + + hg clone https://bitbucket.org/latestrevision/django-mailbox + cd django-mailbox + python setup.py install + +*or* checkout and install the source from the `github repository `_:: + + git clone https://github.com/latestrevision/django-mailbox.git + cd django-mailbox + python setup.py install + +After you have installed the package, +you should add ``django_mailbox`` to the ``INSTALLED_APPS`` setting in your project's ``settings.py`` file. + diff --git a/docs/topics/internet.rst b/docs/topics/internet.rst new file mode 100644 index 0000000..5076daf --- /dev/null +++ b/docs/topics/internet.rst @@ -0,0 +1,23 @@ + +POP3 and IMAP Mailboxes +----------------------- + +Mailbox URIs are in the normal URI format:: + + protocol://username:password@domain + +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 your URI. +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:: + + pop3+ssl://youremailaddress%40gmail.com:1234@pop.gmail.com + diff --git a/docs/topics/mailbox_types.rst b/docs/topics/mailbox_types.rst new file mode 100644 index 0000000..94e176a --- /dev/null +++ b/docs/topics/mailbox_types.rst @@ -0,0 +1,24 @@ + +Supported Mailbox Types +======================= + +Django Mailbox supports polling both common internet mailboxes like 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://`` + Maildir ``maildir://`` + Mbox ``mbox://`` + Babyl ``babyl://`` + MH ``mh://`` + MMDF ``mmdf://`` + Piped Mail *empty* See `Receiving mail directly from Exim4 or Postfix via a pipe`_ + ============ ============== =============================================================== + +.. WARNING:: + This will delete 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. diff --git a/docs/topics/piped.rst b/docs/topics/piped.rst new file mode 100644 index 0000000..75f1903 --- /dev/null +++ b/docs/topics/piped.rst @@ -0,0 +1,59 @@ + +Receiving mail directly from Exim4 or Postfix via a pipe +======================================================== + +Django Mailbox's ``processincomingmessage`` management command accepts, via ``stdin``, incoming messages. +You can configure Postfix or Exim4 to pipe incoming mail to this management command +to import messages directly without polling. + +You need not configure mailbox settings when piping-in messages, +mailbox entries will be automatically created matching the e-mail address to which incoming messages are sent, +but if you would like to specify the mailbox name, +you may provide a single argument to the ``processincmingmessage`` command +specifying the name of the mailbox you would like it to use (and, if neccessary, create). + +Receiving Mail from Exim4 +------------------------- + +To configure Exim4 to receive incoming mail, +start by adding 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 + +Make sure that the e-mail addresses you would like handled by Django Mailbox are not handled by another router; +you may need to disable some existing routers. + +Change the contents of ``local_parts`` to match a colon-delimited list of usernames for which you would like to receive mail. +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``. + +Next, 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, transport configuration should be altered to match your environment. +First, modify the ``command`` setting such that it points at the proper python executable +(if you're using a virtual environment, you'll want to direct that at the python executable 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. + diff --git a/docs/topics/polling.rst b/docs/topics/polling.rst new file mode 100644 index 0000000..45f8ec7 --- /dev/null +++ b/docs/topics/polling.rst @@ -0,0 +1,29 @@ + +Getting incoming mail +--------------------- + +If you are utilizing one of the polling methods above, +you will need to periodically poll the mailbox for messages using one of the below methods. +If you are receiving mail directly from a mailserver via a pipe +-- using the ``processincomingmessage`` management command -- +you need not concern yourself with this section. + +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 diff --git a/docs/topics/settings.rst b/docs/topics/settings.rst new file mode 100644 index 0000000..9d01f55 --- /dev/null +++ b/docs/topics/settings.rst @@ -0,0 +1,12 @@ + +Settings +======== + ++---------------------------------------+--------------+-------------------------------------------------------------------------+ +| Setting | Default | Notes | ++=======================================+==============+=========================================================================+ +| ``DJANGO_MAILBOX_ADMIN_ENABLED`` | ``True`` | Controls whether mailboxes appear in the Django Admin. | ++---------------------------------------+--------------+-------------------------------------------------------------------------+ +| ``DJANGO_MAILBOX_SKIPPED_EXTENSIONS`` | ``['.p7s']`` | A list of extensions to skip when processing email message attachments. | ++---------------------------------------+--------------+-------------------------------------------------------------------------+ + diff --git a/docs/topics/signal.rst b/docs/topics/signal.rst new file mode 100644 index 0000000..b778081 --- /dev/null +++ b/docs/topics/signal.rst @@ -0,0 +1,13 @@ + +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, ) + diff --git a/readme.rst b/readme.rst index e05cc7d..8871e65 100755 --- a/readme.rst +++ b/readme.rst @@ -1,5 +1,3 @@ -.. image:: https://travis-ci.org/latestrevision/django-mailbox.png?branch=master - How many times have you had to consume some sort of POP3, IMAP, or local mailbox for incoming content, or had to otherwise construct an application driven by e-mail? One too many times, I'm sure. @@ -7,194 +5,12 @@ One too many times, I'm sure. This small Django application will allow you to specify 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). -Installation -============ - -You can either install from pip:: - - pip install django-mailbox - -*or* checkout and install the source from the `bitbucket repository `_:: - - hg clone https://bitbucket.org/latestrevision/django-mailbox - cd django-mailbox - python setup.py install - -*or* checkout and install the source from the `github repository `_:: - - git clone https://github.com/latestrevision/django-mailbox.git - cd django-mailbox - python setup.py install - -After you have installed the package, -you should add ``django_mailbox`` to the ``INSTALLED_APPS`` setting in your project's ``settings.py`` file. - -Polling for mail in POP3/IMAP or a local mailbox -================================================ - -Django Mailbox supports polling both common internet mailboxes like 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://`` - Maildir ``maildir://`` - Mbox ``mbox://`` - Babyl ``babyl://`` - MH ``mh://`` - MMDF ``mmdf://`` - Piped Mail *empty* See `Receiving mail directly from Exim4 or Postfix via a pipe`_ - ============ ============== =============================================================== - -.. WARNING:: - This will delete 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. - -POP3 and IMAP Mailboxes ------------------------ - -Mailbox URIs are in the normal URI format:: - - protocol://username:password@domain - -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 your URI. -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:: - - pop3+ssl://youremailaddress%40gmail.com:1234@pop.gmail.com - -Local File-based Mailboxes --------------------------- - -If you happen to want to consume a file-based mailbox like an Maildir, Mbox, Babyl, MH, or MMDF mailbox, -you can use this too by entering the appropriate 'protocol' in the URI. -If you had a maildir, for example, at ``/var/mail/``, you would enter a URI like:: - - maildir:///var/mail - -Note that there is an additional ``/`` in the above URI after the protocol; -this is important. - -Getting incoming mail ---------------------- - -If you are utilizing one of the polling methods above, -you will need to periodically poll the mailbox for messages using one of the below methods. -If you are receiving mail directly from a mailserver via a pipe --- using the ``processincomingmessage`` management command -- -you need not concern yourself with this section. - -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 accepts, via ``stdin``, incoming messages. -You can configure Postfix or Exim4 to pipe incoming mail to this management command -to import messages directly without polling. - -You need not configure mailbox settings when piping-in messages, -mailbox entries will be automatically created matching the e-mail address to which incoming messages are sent, -but if you would like to specify the mailbox name, -you may provide a single argument to the ``processincmingmessage`` command -specifying the name of the mailbox you would like it to use (and, if neccessary, create). - -Receiving Mail from Exim4 -------------------------- - -To configure Exim4 to receive incoming mail, -start by adding 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 - -Make sure that the e-mail addresses you would like handled by Django Mailbox are not handled by another router; -you may need to disable some existing routers. - -Change the contents of ``local_parts`` to match a colon-delimited list of usernames for which you would like to receive mail. -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``. - -Next, 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, transport configuration should be altered to match your environment. -First, modify the ``command`` setting such that it points at the proper python executable -(if you're using a virtual environment, you'll want to direct that at the python executable 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 -======================================= - -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, ) - -Settings -======== - -+---------------------------------------+--------------+-------------------------------------------------------------------------+ -| Setting | Default | Notes | -+=======================================+==============+=========================================================================+ -| ``DJANGO_MAILBOX_ADMIN_ENABLED`` | ``True`` | Controls whether mailboxes appear in the Django Admin. | -+---------------------------------------+--------------+-------------------------------------------------------------------------+ -| ``DJANGO_MAILBOX_SKIPPED_EXTENSIONS`` | ``['.p7s']`` | A list of extensions to skip when processing email message attachments. | -+---------------------------------------+--------------+-------------------------------------------------------------------------+ +.. image:: https://travis-ci.org/latestrevision/django-mailbox.png?branch=master +- Documentation for django-mailbox is available on + `ReadTheDocs `_. +- Please post issues on + `BitBucket `_. +- Test status available on + `Travis-CI `_.