<commit_before>==================
Django Post Office
==================

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
* Multi backend support
* 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
* Supports multilingual email templates (i18n)


Dependencies
============

* `django >= 1.4 <http://djangoproject.com/>`_
* `django-jsonfield <https://github.com/bradjasper/django-jsonfield>`_


Installation
============

|Build Status|


* Install from PyPI (or you `manually download from PyPI <http://pypi.python.org/pypi/django-post_office>`_)::

    pip install django-post_office

* Add ``post_office`` to your INSTALLED_APPS in django's ``settings.py``:

.. code-block:: python

    INSTALLED_APPS = (
        # other apps
        "post_office",
    )

* Run ``syncdb``::

    python manage.py syncdb

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

    EMAIL_BACKEND = 'post_office.EmailBackend'

If you're still on Django <= 1.6 and use South to manage your migrations,
you'll need to put the following in ``settings.py``:

.. code-block:: python

    SOUTH_MIGRATION_MODULES = {
        "post_office": "post_office.south_migrations",
    }


Quickstart
==========

Send a simple email is really easy:

.. code-block:: python

    from post_office import mail

    mail.send(
        '<EMAIL>', # List of email addresses also accepted
        '<EMAIL>',
        subject='My email',
        message='Hi there!',
        html_message='Hi <strong>there</strong>!',
    )


If you want to use templates, ensure that Django's admin interface is enabled. Create an
``EmailTemplate`` instance via ``admin`` and do the following:

.. code-block:: python

    from post_office import mail

    mail.send(
        '<EMAIL>', # List of email addresses also accepted
        '<EMAIL>',
        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 the
command 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::

    * * * * * (/usr/bin/python manage.py send_queued_mail >> send_mail.log 2>&1)

or, if you use uWSGI_ as application
server, add this short snipped  to the project's ``wsgi.py`` file:

.. code-block:: python
    :caption: wsgi.py

    from django.core.wsgi import get_wsgi_application
    
    application = get_wsgi_application()
    
    # add this block of code
    try:
        import uwsgidecorators
        from django.core.management import call_command
    
        @uwsgidecorators.timer(10)
        def send_queued_mail(num):
            """Send queued mail every 10 seconds"""
            call_command('send_queued_mail')
    
    except ImportError:
        print("uwsgidecorators not found. Cron and timers are disabled")

Note, ``uwsgidecorators`` are available only if you start your application with **uWSGI**.
However, Django's internal ``./manange.py runserver`` also access this file, therefore
wrap the block into an exception handler as shown above.

This configuration is very useful in environments, such as Docker containers, where you
don't have a running cron-daemon.


Usage
=====

mail.send()
-----------

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

+-------------------+----------+-------------------------------------------------+
| Argument          | Required | Description                                     |
+-------------------+----------+-------------------------------------------------+
| recipients        | Yes      | list of recipient email addresses               |<commit_msg>How to use uwsgi timers<commit_after>==================
Django Post Office
==================

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
* Multi backend support
* 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
* Supports multilingual email templates (i18n)


Dependencies
============

* `django >= 1.4 <http://djangoproject.com/>`_
* `django-jsonfield <https://github.com/bradjasper/django-jsonfield>`_


Installation
============

|Build Status|


* Install from PyPI (or you `manually download from PyPI <http://pypi.python.org/pypi/django-post_office>`_)::

    pip install django-post_office

* Add ``post_office`` to your INSTALLED_APPS in django's ``settings.py``:

.. code-block:: python

    INSTALLED_APPS = (
        # other apps
        "post_office",
    )

* Run ``syncdb``::

    python manage.py syncdb

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

    EMAIL_BACKEND = 'post_office.EmailBackend'

If you're still on Django <= 1.6 and use South to manage your migrations,
you'll need to put the following in ``settings.py``:

.. code-block:: python

    SOUTH_MIGRATION_MODULES = {
        "post_office": "post_office.south_migrations",
    }


Quickstart
==========

Send a simple email is really easy:

.. code-block:: python

    from post_office import mail

    mail.send(
        '<EMAIL>', # List of email addresses also accepted
        '<EMAIL>',
        subject='My email',
        message='Hi there!',
        html_message='Hi <strong>there</strong>!',
    )


If you want to use templates, ensure that Django's admin interface is enabled. Create an
``EmailTemplate`` instance via ``admin`` and do the following:

.. code-block:: python

    from post_office import mail

    mail.send(
        '<EMAIL>', # List of email addresses also accepted
        '<EMAIL>',
        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 the
command 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::

    * * * * * (/usr/bin/python manage.py send_queued_mail >> send_mail.log 2>&1)

or, if you use uWSGI_ as application server, add this short snipped  to the
project's ``wsgi.py`` file:

.. code-block:: python

    from django.core.wsgi import get_wsgi_application
    
    application = get_wsgi_application()
    
    # add this block of code
    try:
        import uwsgidecorators
        from django.core.management import call_command
    
        @uwsgidecorators.timer(10)
        def send_queued_mail(num):
            """Send queued mail every 10 seconds"""
            call_command('send_queued_mail', processes=1)
    
    except ImportError:
        print("uwsgidecorators not found. Cron and timers are disabled")

Alternatively you can also use the decorator ``@uwsgidecorators.cron(minute, hour, day, month, weekday)``.
This will schedule a task at specific times. Use ``-1`` to signal any time, it corresponds to the ``*``
in cron.

Please note that ``uwsgidecorators`` are available only, if the application has been started
with **uWSGI**. However, Django's internal ``./manange.py runserver`` also access this file,
therefore wrap the block into an exception handler as shown above.

This configuration is very useful in environments, such as Docker containers, where you
don't have a running cron-daemon.


Usage
=====

mail.send()
-----------

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

+-------------------+----------+-------------------------------------------------+
| Argument          | Required | Description                                     |
+-------------------+----------+-------------------------------------------------+
| recipients        | Yes      | list of recipient email addresses               |
{'fraction_non_alphanumeric': 0.14779429110639303, 'fraction_numerical': 0.003066761028544468, 'mean_word_length': 2.8073641670408622, 'pattern_counts': {'":': 2, '<': 27, '<?xml version=': 0, '>': 33, 'https://': 2, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 5, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6974013', 'n_tokens_mistral': 2436, 'n_tokens_neox': 2301, 'n_words': 860}