kinto-emailer 0.2.0

Kinto emailer plugin

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 = [e-mail]

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

See more details about Pyramid Mailer configuration.

Development

Use a fake emailer that write emails files to disk:

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:

{
  "kinto-emailer": {
    "hooks": [{
      "template": "Something happened!",
      "recipients": ['Security reviewers <[e-mail]>']
    }]
  }
}

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 <[e-mail]>")

Recipients

The list of recipients can either contain:

• Email adresses (eg. [e-mail] or "Joe Doe <[e-mail]>")

• 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:[e-mail]).

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 <[e-mail]>']
    }, {
      "resource_name": "collection",
      "action": "updated",
      "template": "Collection updated!",
      "recipients": ["Security reviewers <[e-mail]>"]
    }]
  }
}

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

• root_url

• client_address

• user_agent

For example:

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

See Kinto core notifications.

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.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 <[e-mail]>

• Rémy Hubscher <[e-mail]>

• Mathieu Leplatre <[e-mail]>