Kinto emailer plugin
Project description
kinto-emailer send emails when some events arise (e.g. new records have been created). It relies on Pyramid Mailer for the sending part.
Install
pip install kinto-emailer
Setup
In the Kinto settings:
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
# mail.queue_path = NoneIf mail.queue_path is set, the emails are storage in a local Maildir queue.
See more details about Pyramid Mailer configuration.
Development
Use a fake emailer that write emails files to disk:
mail.debug_mailer = trueHow does it work?
Some information — like monitored action or list of recipients — are defined in the collection or the bucket metadata. When an event occurs, the plugin sends emails if one of the expected condition is met.
Usage
The metadata on the collection (or the bucket) must look like this:
{
"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.
The metadata of the collection override the bucket metadata, they are not merged.
Optional:
subject (e.g. "An action was performed")
sender (e.g. "Kinto team <developers@kinto-storage.org>")
Recipients
The list of recipients can either contain:
Email adresses (eg. alice@wonderland.com or "Joe Doe <jon@doe.com>")
Group URI (eg. /buckets/staging/groups/reviewers)
With group URIs, the email recipients will be expanded with the group members principals look like email addresses (eg. ldap:peace@world.org).
Selection
It is possible to define several hooks, and filter on some condition. For example:
{
"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)
collection_id (default: all)
record_id (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
root_url
client_address
user_agent
For example:
{user_id} has {action}d a {resource_name} in {bucket_id}.
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.3.0 (2017-01-30)
New features
Support configuration from bucket metadata (fixes #27)
Send mail to local Maildir queue if mail.queue_path setting is defined (ref #3)
Bug fixes
Fix support of batch requests (fixes #24)
0.2.0 (2017-01-27)
New features
List of recipients can now contain groups URIs. The principals from the specified group that look like email addresses will be used as recipients (fixes #6)
Support new variables like server root url or client IP address in email template (fixes #22)
Add some validation when defining kinto-emailer settings in collections metadata (fixes #21)
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>
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.
