README.txt

=====
Usage
=====

django-mailing was developed to:
 * send emails in ASCII or HTML
 * support email templating with headers and footers
 * support multilingual environments
 * optionally use SendGrid to categorize email statistics and sync email lists
 * optionally support celery for queuing mail sending and/or processing in background processes

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

Available on PyPi::

    pip install django-mailing

Configuration
=============

Add to your installed apps in your setting.py file::

    INSTALLED_APPS = (
    ...
    'mailing',
    )

settings.DEFAULT_FROM_EMAIL
---------------------------

You need to set your default from email::

    DEFAULT_FROM_EMAIL = 'contact@mydomain.com'


settings.MAILING_USE_SENDGRID
-----------------------------

Boolean to indicate you have configured Django to use SendGrid::

    MAILING_USE_SENDGRID = True

The impact is you now have additional SendGrid capabilities such as the ability to:
 * categorize emails sent
 * manage/sync mailing lists (currently not implemented)
 * plus all the good stuff they do on their side.

settings.MAILING_MAILTO_HIJACK
------------------------------

You can hijack email sent by your app to redirect to another email. Quite practical when developing or testing with external email addresses::

    MAILING_MAILTO_HIJACK = 'me@mydomain.com'

If defined, every outgoind email will be sent to me@mydomain.com. For debugging/testing purposes, the following header is added to the email::

    X-MAILER-ORIGINAL-MAILTO: me@mydomain.com

It will contain what would have been the original "To" header if we hadn't hijacked it

settings.MAILING_USE_CELERY
---------------------------

Boolean indicating celery is configured and you want to send/process email related stuff in background::

    MAILING_USE_CELERY = True

For example, you can configure your app to use celery by installing a redis server.

Your settings would also need to include things like::

    INSTALLED_APPS = (
        #
        # ...
        #

        'celery',
        'djcelery',

        #
        # ...
        #

        'mailing',

        #
        # ...
        #
    )
    
    # 
    # ...
    #
    
    # Celery Configuration. Ref.: http://celery.github.com/celery/configuration.htm
    # -------------------------------------
    os.environ["CELERY_LOADER"] = "django"
    djcelery.setup_loader()

    BROKER_TRANSPORT = "redis"
    BROKER_HOST = "localhost"  # Maps to redis host.
    BROKER_PORT = 6379         # Maps to redis port.
    BROKER_VHOST = "0"         # Maps to database number.

    CELERY_IGNORE_RESULT = False
    CELERY_RESULT_BACKEND = "redis"
    CELERY_REDIS_HOST = "localhost"
    CELERY_REDIS_PORT = 6379
    CELERY_REDIS_DB = 0

When running the celery daemon, you need to include the ``mailing`` app in the tasks through the ``include`` parameter. Example::

    manage.py celeryd --verbosity=2 --beat --schedule=celery --events --loglevel=INFO -I mailing

You therefore could run a separate celery daemon to run your mailing tasks independently of other tasks if the need arises.

settings.MAILING_LANGUAGES
--------------------------

Not yet implemented.

Replacing the core django send_mail function
--------------------------------------------

To replace Django's core send_mail function to add support for email templates, SendGrid integration and background celery sending, add the following code to your settings file::

    import sys
    from mailing.mail import send_email_default
    try:
        from django.core import mail 
        mail.send_mail = send_email_default
        sys.modules['django.core.mail'] = mail
    except ImportError:
        pass


Using django-mailing
====================

Simple multi-part send_mail replacement
---------------------------------------

You can using mailing.send_email instead of Django's send_mail to send multi-part messages::

    send_email(recipients, subject, text_content=None, html_content=None, from_email=settings.DEFAULT_FROM_EMAIL, category=None, fail_silently=False, bypass_queue=False)

Parameters are:
 * ``recipients`` is a list of email addresses to send the email to
 * ``subject`` is the subject of your email
 * ``text_content`` is the ASCII content of the email
 * ``html_content`` is the HTML content of the email
 * ``from_email`` is a string and is the sender's address
 * ``category`` is a string and is used to define SendGrid's X-SMTPAPI's category header

You must supply at least text_content or html_content. If both aren't supplied, an exception will be raised. If only one of the two is supplied, the email will be sent in the corresponding format. If both content are supplied, a multi-part email will be sent.

Example usage::

    from mailing import send_email

    send_email(['test1@mydomain.com', 'test@mydomain.com'], 'Testing 1,2,3...', 'Text Body', 'HTML Body', category='testing')

Rendering and sending emails using templates
--------------------------------------------

To use Django templates to generate dynamic emails, similar to using ``render_with_context`` in a Django view, use the ``render_send_email`` shortcut::

    render_send_email(recipients, template, data, from_email=settings.DEFAULT_FROM_EMAIL, subject=None, category=None, fail_silently=False, language='en', bypass_queue=False)

Parameters are:
 * ``recipients`` is a list of email addresses to send the email to
 * ``template`` the path to your Django templates, without any extension
 * ``data`` data context dictionnary to render the template
 * ``from_email`` is a string and is the sender's address
 * ``subject`` is the subject of your email
 * ``category`` is a string and is used to define SendGrid's X-SMTPAPI's category header

Example::

    def send_welcome_email(user):
        from mailing.shortcuts import render_send_email
    
        render_send_email(['test1@mydomain.com', 'test@mydomain.com'], 'users/welcome', {'user': user}, category='welcome')

in your app, you would need the following template files with the right extensions:
 * ``templates/users/welcome.txt``
 * ``templates/users/welcome.html``
 * ``templates/users/welcome.subject``

The subject template file can be omitted but you then need to supply the ``subject`` parameter. If you do not create a template with a .txt or a .html extension, then the associated format won't be included in the email. So, if you want to only send ASCII messages, do not create a .html file.

Example without using a subject template::

    render_send_email(['test1@mydomain.com', 'test@mydomain.com'], 'app/welcome', data, subject='Welcome new user', category='welcome')

Templates
---------

The following templates are defined and used by django-mailing and should be overriten in your own templates:
 * ``templates/mailing/base.txt``
 * ``templates/mailing/base.html``

These are used to define your email overall look like the header and footer. The only requirement is to include the ``{{ content }}`` template variable. It is there than the supplied content of your email will be inserted in your base template.

LICENSE
=======

Copyright (c) 2009 Jerome Paradis, Alain Carpentier and contributors

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.