Skip to main content

Kinto emailer plugin

Project description

https://github.com/Kinto/kinto-emailer/actions/workflows/tests.yml/badge.svg https://img.shields.io/pypi/v/kinto-emailer.svg

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_remote_settings.signer.events.ReviewRequested, kinto_remote_settings.signer.events.ReviewApproved, kinto_remote_settings.signer.events.ReviewRejected

If a filter value starts with the special character ^, then the matching will consider the filter value to be a regular expression.

For example, in order to exclude a specific collection_id, set the filter value to: ^(?!normandy-recipes$).

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

  • settings[name]

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

Releasing

  1. Create a release on Github on https://github.com/Kinto/kinto-emailer/releases/new

  2. Create a new tag X.Y.Z (This tag will be created from the target when you publish this release.)

  3. Generate release notes

  4. Publish release

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

Uploaded Source

Built Distribution

kinto_emailer-3.0.1-py3-none-any.whl (7.5 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: kinto-emailer-3.0.1.tar.gz
  • Upload date:
  • Size: 18.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/4.0.2 CPython/3.11.7

File hashes

Hashes for kinto-emailer-3.0.1.tar.gz
Algorithm Hash digest
SHA256 3d565b81c869cb15e5793537e9ddb0a282a2d8c3493d88ab1d5e6b05f9e26f3e
MD5 04c80e18106865c71508dbd8b6614743
BLAKE2b-256 9c7e4a3236fc21179fb01181fe75654d3474d3e56147ef82ef7f5fa071af3881

See more details on using hashes here.

File details

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

File metadata

File hashes

Hashes for kinto_emailer-3.0.1-py3-none-any.whl
Algorithm Hash digest
SHA256 e3d481751cbc5971eb077766691f9a2d6166b5c78964442d90273223ad1ece53
MD5 c05e20877d19193964c322e866ae820f
BLAKE2b-256 b23371d13f38be23cfcaa63a67319e8768df657479a246a0b7457d8cee10d3dd

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