Kinto Emailer
#############
.. image:: https://github.com/Kinto/kinto-emailer/actions/workflows/tests.yml/badge.svg
:target: https://github.com/Kinto/kinto-emailer/actions
.. image:: https://img.shields.io/pypi/v/kinto-emailer.svg
:target: https://pypi.python.org/pypi/kinto-emailer
**kinto-emailer** send emails when some events arise (e.g. new records have
been created). It relies on `Pyramid Mailer <https://github.com/Pylons/pyramid_mailer/>`_
for the sending part.
Install
=======
::
pip install kinto-emailer
Setup
=====
In the `Kinto <http://kinto.readthedocs.io/>`_ settings:
.. code-block:: ini
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 <http://docs.pylonsproject.org/projects/pyramid_mailer/en/latest/#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:
.. code-block:: ini
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:
.. code-block:: js
{
"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:
.. code-block:: js
{
"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 <http://kinto.readthedocs.io/en/5.3.0/core/notifications.html#payload>`_.
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
Raw data
{
"_id": null,
"home_page": "",
"name": "kinto-emailer",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "web services",
"author": "",
"author_email": "Mozilla Services <developers@kinto-storage.org>",
"download_url": "https://files.pythonhosted.org/packages/9c/7e/4a3236fc21179fb01181fe75654d3474d3e56147ef82ef7f5fa071af3881/kinto-emailer-3.0.1.tar.gz",
"platform": null,
"description": "Kinto Emailer\n#############\n\n.. image:: https://github.com/Kinto/kinto-emailer/actions/workflows/tests.yml/badge.svg\n :target: https://github.com/Kinto/kinto-emailer/actions\n\n.. image:: https://img.shields.io/pypi/v/kinto-emailer.svg\n :target: https://pypi.python.org/pypi/kinto-emailer\n\n**kinto-emailer** send emails when some events arise (e.g. new records have\nbeen created). It relies on `Pyramid Mailer <https://github.com/Pylons/pyramid_mailer/>`_\nfor the sending part.\n\n\nInstall\n=======\n\n::\n\n pip install kinto-emailer\n\nSetup\n=====\n\nIn the `Kinto <http://kinto.readthedocs.io/>`_ settings:\n\n.. code-block:: ini\n\n kinto.includes = kinto_emailer\n\n mail.default_sender = kinto@restmail.net\n\n # mail.host = localhost\n # mail.port = 25\n # mail.username = None\n # mail.password = None\n # mail.tls = False\n # mail.queue_path = None\n\nIf ``mail.queue_path`` is set, the emails are storage in a local Maildir queue.\n\nSee `more details about Pyramid Mailer configuration <http://docs.pylonsproject.org/projects/pyramid_mailer/en/latest/#configuration>`_.\n\nValidate configuration\n----------------------\n\nThe following command will send a dummy email to the specified recipient or will fail if the configuration is not correct:\n\n::\n\n $ kinto-send-email config/kinto.ini testemailer@restmail.net\n\n\nDevelopment\n-----------\n\nUse a fake emailer that write emails files to disk:\n\n.. code-block:: ini\n\n mail.debug_mailer = true\n\n\nHow does it work?\n=================\n\nSome information \u2014 like monitored action or list of recipients \u2014 are defined in\nthe collection or the bucket metadata. When an event occurs, the plugin sends emails if one of\nthe expected condition is met.\n\n\nUsage\n=====\n\nThe metadata on the collection (or the bucket) must look like this:\n\n.. code-block:: js\n\n {\n \"kinto-emailer\": {\n \"hooks\": [{\n \"template\": \"Something happened!\",\n \"recipients\": ['Security reviewers <security-reviews@mozilla.com>']\n }]\n }\n }\n\nIn the above example, every action on the collection metadata or any record in that\ncollection will trigger an email notification.\n\nThe metadata of the collection override the bucket metadata, they are not merged.\n\nOptional:\n\n* ``subject`` (e.g. ``\"An action was performed\"``)\n* ``sender`` (e.g. ``\"Kinto team <developers@kinto-storage.org>\"``)\n\n\nRecipients\n----------\n\nThe list of recipients can either contain:\n\n* Email adresses (eg. ``alice@wonderland.com`` or ``\"Joe Doe <jon@doe.com>\"``)\n* Group URI (eg. ``/buckets/staging/groups/reviewers``)\n\nWith group URIs, the email recipients will be expanded with the group members\nprincipals look like email addresses (eg. ``ldap:peace@world.org``).\n\n\nSelection\n---------\n\nIt is possible to define several *hooks*, and filter on some condition. For example:\n\n.. code-block:: js\n\n {\n \"kinto-emailer\": {\n \"hooks\": [{\n \"resource_name\": \"record\",\n \"action\": \"create\",\n \"template\": \"Record created!\",\n \"recipients\": ['Security reviewers <security-reviews@mozilla.com>']\n }, {\n \"resource_name\": \"collection\",\n \"action\": \"updated\",\n \"template\": \"Collection updated!\",\n \"recipients\": [\"Security reviewers <security-reviews@mozilla.com>\"]\n }]\n }\n }\n\nThe possible filters are:\n\n* ``resource_name``: ``record`` or ``collection`` (default: all)\n* ``action``: ``create``, ``update``, ``delete`` (default: all)\n* ``collection_id`` (default: all)\n* ``record_id`` (default: all)\n* ``event``: ``kinto.core.events.AfterResourceChanged`` (default), or\n ``kinto_remote_settings.signer.events.ReviewRequested``, ``kinto_remote_settings.signer.events.ReviewApproved``,\n ``kinto_remote_settings.signer.events.ReviewRejected``\n\nIf a filter value starts with the special character ``^``, then the matching will consider the filter value to be a regular expression.\n\nFor example, in order to exclude a specific ``collection_id``, set the filter value to: ``^(?!normandy-recipes$)``.\n\n\nTemplate\n--------\n\nThe template string can have placeholders:\n\n* ``bucket_id``\n* ``id``: record or collection ``id``\n* ``user_id``\n* ``resource_name``\n* ``uri``\n* ``action``\n* ``timestamp``\n* ``root_url``\n* ``client_address``\n* ``user_agent``\n* ``settings[name]``\n\nFor example:\n\n``{user_id} has {action}d a {resource_name} in {bucket_id}.``\n\nSee `Kinto core notifications <http://kinto.readthedocs.io/en/5.3.0/core/notifications.html#payload>`_.\n\n\nRunning the tests\n=================\n\nTo run the unit tests::\n\n $ make tests\n\nFor the functional tests, run a Kinto instance in a separate terminal::\n\n $ make run-kinto\n\nAnd start the test suite::\n\n $ make functional\n\n\nReleasing\n=========\n\n1. Create a release on Github on https://github.com/Kinto/kinto-emailer/releases/new\n2. Create a new tag `X.Y.Z` (*This tag will be created from the target when you publish this release.*)\n3. Generate release notes\n4. Publish release\n",
"bugtrack_url": null,
"license": "Copyright 2017 - Mozilla Corporation Licensed under the Apache License, Version 2.0 (the \"License\"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ",
"summary": "Kinto emailer plugin",
"version": "3.0.1",
"project_urls": {
"Repository": "https://github.com/Kinto/kinto-emailer"
},
"split_keywords": [
"web",
"services"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b23371d13f38be23cfcaa63a67319e8768df657479a246a0b7457d8cee10d3dd",
"md5": "c05e20877d19193964c322e866ae820f",
"sha256": "e3d481751cbc5971eb077766691f9a2d6166b5c78964442d90273223ad1ece53"
},
"downloads": -1,
"filename": "kinto_emailer-3.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c05e20877d19193964c322e866ae820f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 7533,
"upload_time": "2024-01-19T10:48:30",
"upload_time_iso_8601": "2024-01-19T10:48:30.766925Z",
"url": "https://files.pythonhosted.org/packages/b2/33/71d13f38be23cfcaa63a67319e8768df657479a246a0b7457d8cee10d3dd/kinto_emailer-3.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "9c7e4a3236fc21179fb01181fe75654d3474d3e56147ef82ef7f5fa071af3881",
"md5": "04c80e18106865c71508dbd8b6614743",
"sha256": "3d565b81c869cb15e5793537e9ddb0a282a2d8c3493d88ab1d5e6b05f9e26f3e"
},
"downloads": -1,
"filename": "kinto-emailer-3.0.1.tar.gz",
"has_sig": false,
"md5_digest": "04c80e18106865c71508dbd8b6614743",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 18410,
"upload_time": "2024-01-19T10:48:32",
"upload_time_iso_8601": "2024-01-19T10:48:32.253608Z",
"url": "https://files.pythonhosted.org/packages/9c/7e/4a3236fc21179fb01181fe75654d3474d3e56147ef82ef7f5fa071af3881/kinto-emailer-3.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-19 10:48:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Kinto",
"github_project": "kinto-emailer",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "kinto-emailer"
}
JSON
