Django Post Office is a simple app to send and manage your emails in Django.Some awesome features are:

* Allows you to send email asynchronously* Supports HTML email* Supports database based email templates* Built in scheduling support * Works well with task queues like `RQ <http: python-rq.org="">`_ or `Celery <http: www.celeryproject.org="">`_* Uses multiprocessing to send a large number of emails in parallel

* Set ``post_office.EmailBackend`` as your ``EMAIL_BACKEND`` in django's ``settings.py``::

EMAIL_BACKEND = 'post_office.EmailBackend'

Quickstart==========

To get started, make sure you have Django's admin interface enabled. Create an``EmailTemplate`` instance via ``/admin`` and you can start sending emails.

.. code-block:: python

from post_office import mail

mail.send( ['recipient1@example.com'], 'from@example.com', template='welcome_email', # Could be an EmailTemplate instance or name context={'foo': 'bar'}, )

The above command will put your email on the queue so you can use thecommand in your webapp without slowing down the request/response cycle too much.To actually send them out, run ``python manage.py send_queued_mail``.You can schedule this management command to run regularly via cron::

``mail.send`` is the most important function in this library, it takes thesearguments:

================== ======== =========================Argument Required Description================== ======== =========================recipients Yes list of recipient email addressessender No Defaults to ``settings.DEFAULT_FROM_EMAIL``, display name is allowed (``John <john@example.com>``)template No ``EmailTemplate`` instance or namecontext No A dictionary used when email is being renderedsubject No Email subject (if ``template`` is not specified)message No Email content (if ``template`` is not specified)html_message No Email's HTML content (if ``template`` is not specified)headers No A dictionary of extra headers to put on the messagescheduled_time No A date/datetime object indicating when the email should be sentpriority No ``high``, ``medium``, ``low`` or ``now`` (send immediately)attachments No Email attachments - A dictionary where the keys are the wanted filenames, and the values are either files or file-like objects, or full path of the file.render_on_delivery No Setting this to ``True`` causes email to be rendered from ``template`` during delivery. Content is never stored in the DB. Usage may result in significant space savings.================== ======== =========================

Here are a few examples.

If you just want to send out emails without using database templates. You cancall the ``send`` command without the ``template`` argument.

``post_office`` is also task queue friendly. Passing ``now`` as priority into``send_mail`` will deliver the email right away (instead of queuing it),regardless of how many emails you have in your queue:

``post-office`` supports Django's template tags and variables when.For example, if you put "Hello, {{ name }}" in the subject line and pass in``{'name': 'Alice'}`` as context, you will get "Hello, Alice" as subject:

EmailTemplate.objects.create( name='morning_greeting', subject='Morning, {{ name|capfirst }}', content='Hi {{ name }}, how are you feeling today?', html_content='Hi <strong>{{ name }}</strong>, how are you feeling today?', )

# This will create an email with the following content: subject = 'Morning, Alice', content = 'Hi alice, how are you feeling today?' content = 'Hi <strong>alice</strong>, how are you feeling today?'

Custom Email Backends---------------------

By default, ``post_office`` uses django's SMTP ``EmailBackend``. If you want touse a different backend, you can do so by changing ``POST_OFFICE_BACKEND``.

For example if you want to use `django-ses <https: github.com="" hmarr="" django-ses="">`_::

POST_OFFICE_BACKEND = 'django_ses.SESBackend'

Management Commands-------------------

* ``send_queued_mail`` - send queued emails, those aren't successfully sent will be marked as ``failed``. If you have a lot of emails, you can pass in ``-p`` or ``--processes`` flag to use multiple processes.

* ``cleanup_mail`` - delete all emails created before an X number of days (defaults to 90).

If you may want to limit the number of emails sent in a batch (sometimes usefulin a low memory environment), use the ``BATCH_SIZE`` argument to limit thenumber of queued emails fetched in one batch.

.. code-block:: python

POST_OFFICE = { 'BATCH_SIZE': 5000 }

Default priority----------------

The default priority for emails is ``medium``, but this can be altered bysetting ``DEFAULT_PRIORITY``. Integration with asynchronous email backends(e.g. based on Celery) becomes trivial when set to ``now``.

.. code-block:: python

POST_OFFICE = { 'DEFAULT_PRIORITY': 'now' }

Performance===========

Caching-------

if Django's caching mechanism is configured, ``post_office`` will cache``EmailTemplate`` instances . If for some reason you want to disable caching,set ``POST_OFFICE_CACHE`` to ``False`` in ``settings.py``:

.. code-block:: python

## All cache key will be prefixed by post_office:template: ## To turn OFF caching, you need to explicitly set POST_OFFICE_CACHE to False in settings POST_OFFICE_CACHE = False

Starting from version 0.6.0, ``post-office`` includes ``mail.send_many()``that's much more performant (generates less database queries) whensending a large number of emails. Since this function uses Django's`bulk_create <https: docs.djangoproject.com="" en="" 1.5="" ref="" models="" querysets="" #bulk-create="">`_ command, it's only usable on Django >= 1.4.

Behavior wise, ``mail.send_many()`` is almost identical to ``mail.send()``,with the exception that it accepts a list of keyword arguments that you'dusually pass into ``mail.send()``:

Version 0.8.1-------------* Fixed a bug that causes context to be saved when ``render_on_delivery`` is False

Version 0.8.0-------------* Added a new setting ``DEFAULT_PRIORITY`` to set the default priority for emails. Thanks Maik Hoepfel (@maikhoepfel)!* ``mail.send()`` gains a ``render_on_delivery`` argument that may potentially result in significant storage space savings.* Uses a new locking mechanism that can detect zombie PID files.

Version 0.7.2-------------* Made a few tweaks that makes ``post_office`` much more efficient on systems with large number of rows (millions).

Version 0.5.0-------------* Email sending can now be parallelized using multiple processes (multiprocessing)* Email templates are now validated before save* Fixed a bug where custom headers aren't properly sent

Version 0.4.0-------------* Added support for sending emails with custom headers (you'll need to run South when upgrading from earlier versions)* Added support for scheduled email sending* Backend now properly persist emails with HTML alternatives

Version 0.3.1-------------* **IMPORTANT**: ``mail.send`` now expects recipient email addresses as the first argument. This change is to allow optional ``sender`` parameter which defaults to ``settings.DEFAULT_FROM_EMAIL``* Fixed a bug where all emails sent from ``mail.send`` have medium priority

Version 0.3.0-------------* **IMPORTANT**: added South migration. If you use South and had post-office installed before 0.3.0, you may need to manually resolve migration conflicts* Allow unicode messages to be displayed in ``/admin``* Introduced a new ``mail.send`` function that provides a nicer API to send emails* ``created`` fields now use ``auto_now_add``* ``last_updated`` fields now use ``auto_now``