kinto-emailer 0.1.0

Kinto Emailer
#############

.. image:: https://img.shields.io/travis/Kinto/kinto-emailer.svg
:target: https://travis-ci.org/Kinto/kinto-emailer

.. image:: https://img.shields.io/pypi/v/kinto-emailer.svg
:target: https://pypi.python.org/pypi/kinto-emailer

.. image:: https://coveralls.io/repos/Kinto/kinto-emailer/badge.svg?branch=master
:target: https://coveralls.io/r/Kinto/kinto-emailer


**kinto-emailer** send emails when some events arise (e.g. new records have
been created). It relies on `Pyramid Mailer <https://github.com/Pylons/pyramid_mailer/>`_
for the sending part.


Install
=======

::

pip install kinto-emailer

Setup
=====

In the `Kinto <http://kinto.readthedocs.io/>`_ settings:

.. code-block:: ini

kinto.includes = kinto_emailer

mail.default_sender = kinto@restmail.net

# mail.host = localhost
# mail.port = 25
# mail.username = None
# mail.password = None
# mail.tls = False

See `more details about Pyramid Mailer configuration <http://docs.pylonsproject.org/projects/pyramid_mailer/en/latest/#configuration>`_.


Development
-----------

Use a fake emailer that write emails files to disk:

.. code-block:: ini

mail.debug_mailer = true


How does it work?
=================

Some information — like monitored action or list of recipients — are defined in
the collection metadata. When an event occurs, the plugin sends emails if one of
the expected condition is met.


Usage
=====

The metadata on the collection must look like this:

.. code-block:: js

{
"kinto-emailer": {
"hooks": [{
"template": "Something happened!",
"recipients": ['Security reviewers <security-reviews@mozilla.com>']
}]
}
}

In the above example, every action on the collection metadata or any record in that
collection will trigger an email notification.

Optional:

* ``sender`` (e.g.``"Kinto team <developers@kinto-storage.org>"``)


Selection
---------

It is possible to define several *hooks*, and filter on some condition. For example:

.. code-block:: js

{
"kinto-emailer": {
"hooks": [{
"resource_name": "record",
"action": "create",
"template": "Record created!",
"recipients": ['Security reviewers <security-reviews@mozilla.com>']
}, {
"resource_name": "collection",
"action": "updated",
"template": "Collection updated!",
"recipients": ['Security reviewers <security-reviews@mozilla.com>']
}]
}
}

The possible filters are:

* ``resource_name``: ``record`` or ``collection`` (default: all)
* ``action``: ``create``, ``update``, ``delete`` (default: all)
* ``event``: ``kinto.core.events.AfterResourceChanged`` (default), or
``kinto_signer.events.ReviewRequested``, ``kinto_signer.events.ReviewApproved``,
``kinto_signer.events.ReviewRejected``


Template
--------

The template string can have placeholders:

* ``bucket_id``
* ``id``: record or collection ``id``)
* ``user_id``
* ``resource_name``
* ``uri``
* ``action``
* ``timestamp``

For example:

``{user_id} has {action}d a {resource_name} in {bucket_id}.``

See `Kinto core notifications <http://kinto.readthedocs.io/en/5.3.0/core/notifications.html#payload>`_.


Running the tests
=================

To run the unit tests::

$ make tests

For the functional tests, run a Kinto instance in a separate terminal:

::

$ make run-kinto


And start the test suite::

$ make functional


Changelog
=========

This document describes changes between each past release.

0.1.0 (2017-01-25)
------------------

**Initial version**

- Use a list of hooks to configure emails bound to notifications (fixes #11)
- Support *kinto-signer* events (fixes #14)


Contributors
============

* Alexis Métaireau <alexis@notmyidea.org>
* Rémy Hubscher <rhubscher@mozilla.com>
* Mathieu Leplatre <mathieu@mozilla.com>