Metadata-Version: 2.0
Name: kinto-emailer
Version: 0.1.0
Summary: Kinto emailer plugin
Home-page: https://github.com/Kinto/kinto-emailer
Author: Mozilla Services
Author-email: developers@kinto-storage.org
License: Apache License (2.0)
Keywords: web services
Platform: UNKNOWN
Classifier: Programming Language :: Python
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: WSGI :: Application
Classifier: License :: OSI Approved :: Apache Software License
Requires-Dist: kinto (>5)
Requires-Dist: pyramid (<1.8)
Requires-Dist: pyramid-mailer

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>


