Kinto emailer plugin
Project description
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>
#############
.. 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>
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
kinto-emailer-0.1.0.tar.gz
(8.1 kB
view hashes)
Built Distribution
Close
Hashes for kinto_emailer-0.1.0-py2-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | fd078da6615a667d795495d01d011209ee1dd1f32e49c0ef4df6ad3c7b84983a |
|
MD5 | 15aaa65cf6091e2936ab3ac9f20ebc41 |
|
BLAKE2b-256 | 945e085ea667c0bee70b43c9748976df22b0c50153593c834e4378994ba7b830 |