Skip to main content
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

Metadata

Release files for kinto-emailer 3.0.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for kinto-emailer 3.0.2
File Size Uploaded Provenance Actions
kinto_emailer-3.0.2.tar.gz 35.5 kB With provenance Details for kinto_emailer-3.0.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for kinto-emailer 3.0.2
File Interpreter ABI Platform Actions
kinto_emailer-3.0.2-py3-none-any.whl Python 3 none any Details for kinto_emailer-3.0.2-py3-none-any.whl

Total release size: 43.0 kB

Release files / kinto_emailer-3.0.2.tar.gz

Download URL kinto_emailer-3.0.2.tar.gz
Size 35.5 kB
Tags Source
SHA-256 checksum
How to use checksums
c85446c408fb65ffda761e51d46389b447f739153ea87e298faad3a6e4a5739c
BLAKE2b-256 checksum
How to use checksums
6038a47a5c14b80e65f0c0236b5d923f6e2c203dfe53acde2e9442738b65ee06
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.12.8

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jan 31, 2025.

Transparency log

Release files / kinto_emailer-3.0.2-py3-none-any.whl

Download URL kinto_emailer-3.0.2-py3-none-any.whl
Size 7.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ecc639f498ec37ac09c326662b4bc211e3670a4f5197c2422ccb3f7a88e0dc40
BLAKE2b-256 checksum
How to use checksums
05ca9ff87bf89c26350bc1044193d2ee20fe8cf5f74c28bcbf022eb78ef70569
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.12.8

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jan 31, 2025.

Transparency log

Security for kinto-emailer 3.0.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for kinto_emailer-3.0.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jan 31, 2025.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page