.. -*- coding: utf-8 -*-

Email Notifications

===================

Often it is useful to send email notifications out to certain folks when

certain things occur or are noticed within the business logic.  Rattail assumes

that you might define any number of such events for which email should be sent

out, and of course that you may want different recipients etc. for each event.

With this in mind, the following email subsystem exists.

From Code

---------

The Python code is listed before the configuration syntax, as it best

illustrates the *reasoning* behind the config syntax.  Here is a simplistic

notification example:

.. code-block:: python

   from rattail.mail import send_email

   def my_business_logic(config, yesterday_sales):

       max_sales = config.get_int('myapp', 'max_sales')

       if yesterday_sales > max_sales:

           send_email(config, 'sales_max_broken', {'sales': yesterday_sales})

Here also is the API doc for :func:`rattail.mail.send_email()`.

The point here is that ``send_email()`` should require nothing more than a

handle on the current configuration object (which should always be available in

some direct way), a "key" to distinguish the particular type of event for which

the email is being sent, and an optional dictionary to be used as template

context when rendering the email body.

Configuration

-------------

There are really three different aspects to the email configuration.

* **Meta Configuration** - transcends "types" of email notification

* **Generic Configuration** - common to all types of email notification

* **Specific Configuration** - unique to a particular type of email notification

Meta Configuration

^^^^^^^^^^^^^^^^^^

This aspect of configuration consists of settings which have nothing to do with

the "type" of email notification involved.  Instead of listing and describing

them separately (for now), here is a config snippet which defines each:

.. code-block:: ini

   [rattail.mail

   smtp.server = localhost

   smtp.username = mymailuser

   smtp.password = mymailpass

   templates =

           rattail:templates/email

           myproject:templates/email

.. todo::

   Need to explain current limitations of SMTP authentication.

.. todo::

   Need to properly explain email template path setting.

Generic Configuration

^^^^^^^^^^^^^^^^^^^^^

This aspect of configuration consists of settings which may (but need not be)

overridden for any specific "type" of email notification.  That is, they

provide the default value if no specific override exists.  Again, here is a

config snippet which defines each:

.. code-block:: ini

   [rattail.mail]

   default.from = Rattail <rattail@example.com>

   default.to =

        "Admins <admin@example.com>"

        "Managers" <manager@example.com>"

   default.subject = [Rattail] Notification

Note that the "from" address is interpreted as a single address in all cases,