Skip to main content

Kinto emailer plugin

Project description

https://img.shields.io/travis/Kinto/kinto-emailer.svg https://img.shields.io/pypi/v/kinto-emailer.svg https://coveralls.io/repos/Kinto/kinto-emailer/badge.svg?branch=master

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 = None

If mail.queue_path is set, the emails are storage in a local Maildir queue.

See more details about Pyramid Mailer configuration.

Validate configuration

The following command will send a dummy email to the specified recipient or will fail if the configuration is not correct:

$ kinto-send-email config/kinto.ini testemailer@restmail.net

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 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}.

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.

1.0.1 (2017-11-21)

Bug fixes

  • Don’t block on Pyramid 1.8 anymore. (#46)

1.0.0 (2017-06-28)

Bug fixes

  • Fix crash when creating bucket with POST /buckets (fixes #43)

0.4.0 (2017-04-14)

New features

  • Add a validate_setup.py script to check that server can actually send emails

  • Add a kinto-send-email command to test the configuration (fixes #35)

Bug fixes

  • Fix sending notifications by decoupling it from transactions (fixes #38)

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

Project details


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-1.0.1.tar.gz (12.3 kB view details)

Uploaded Source

Built Distribution

kinto_emailer-1.0.1-py3-none-any.whl (16.0 kB view details)

Uploaded Python 3

File details

Details for the file kinto-emailer-1.0.1.tar.gz.

File metadata

File hashes

Hashes for kinto-emailer-1.0.1.tar.gz
Algorithm Hash digest
SHA256 aab392515ab7fc15d8788fde80121bdda45f653f5b3a647acfc5e0fb82f15ad5
MD5 b65c90d7df358653eb5cbccfb43b96bb
BLAKE2b-256 338f7bc033754e10a71f223952436e57ebe3e76e2c6282d82747d4bbc1b0bb6d

See more details on using hashes here.

File details

Details for the file kinto_emailer-1.0.1-py3-none-any.whl.

File metadata

File hashes

Hashes for kinto_emailer-1.0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 4d66c1d4a68b68aa9df55c9d2c09b9496cf644b748967666e02db883881b66b0
MD5 075a49b1f31d09efe14fbdee9b6a15ac
BLAKE2b-256 c927cd5f901d8deef2bbda73e0e724090e25e46388196e5133e89d426e6871c7

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page