tgapp-mailtemplates 0.16.0
Email template management for web applications
Keywords: turbogears2.application

.. image:: https://travis-ci.org/axant/tgapp-mailtemplates.svg?branch=master
   :target: https://travis-ci.org/axant/tgapp-mailtemplates

About mailtemplates
-------------------------

mailtemplates is a Pluggable application for TurboGears2.

mailtemplates provides a dashboard meant for managers of your website (whoever has the ``mailtemplates`` permission) allowing them to customize the templates of the email that are sent from your application.

the templates are stored in a database and both ``sqlalchemy`` and ``ming`` are supported.

kajiki is the template engine used.

Installing
-------------------------------

mailtemplates can work with ``tgext.asyncjob`` or ``tgext.asyncjob``
you can choose by installing with the right bundle::

    pip install "mailtemplates[asyncjob]"

or::

    pip install "mailtemplates[celery]"

if you just want to send emails in a syncronous context then install the base package and plug with ``async_sender`` set to ``None``

Plugging mailtemplates
----------------------------

In your application *config/app_cfg.py* import **plug**::

    from tgext.pluggable import plug

Then at the *end of the file* call plug with mailtemplates::

    plug(base_config, 'mailtemplates')

For configure your default language for email templates, add the ISO 3166-2 code as parameter of the `plug` call::

     plug(base_config, 'mailtemplates', default_language='IT')

If not specified, 'EN' will be the default language for you app.

If you intend to use tgext.celery then plug and configure it **before** plugging mailtemplates with ``async_sender`` option::

    plug(base_config, 'mailtemplates', async_sender='tgext.celery')

and in your ``.ini`` file add under ``celery.CELERY_INCLUDE`` ``mailtemplates.lib.celery_tasks``::

    celery.CELERY_INCLUDE = myapp.lib.celery.tasks mailtemplates.lib.celery_tasks


You will be able to access the plugged application at
*http://localhost:8080/mailtemplates*.

Sending emails
--------------

access to the dashboard and create a mail model, then you can use::

    from mailtemplates.lib import send_email
    send_email(
      recipients=['address@example.com'],
      sender=config.get('mail.username'),
      mail_model_name='test',
      data=dict(test='test string'),
      send_async=True,
    )

in your controllers to actually send the email.

details of params of ``send_email``

- recipients: An array representing the email address of the recipient of the email
- sender: A string representing the email address of the sender of the email
- mail_model_name: The name of the MailModel representing an email
- translation: The language of a TemplateTranslation (e.g. 'EN'). If omitted, the
  default language provided while plugging mailtemplates is used
- data: A dictionary representing the variables used in the email template, like ${name}
- send_async: The email will sent asynchronously if this flag is True

Note on send_async
--------------------

if you are already in an asyncronous context then you can't use tgext.asyncjob with send_async=True,
but you're already in an asyncronous context, so you can just use send_async=False.
If you really need to send email asynchronously from an already asyncronous context, then use tgext.celery