Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/django-ses/django-ses

A Django email backend for Amazon's Simple Email Service
https://github.com/django-ses/django-ses

Last synced: 6 days ago
JSON representation

A Django email backend for Amazon's Simple Email Service

Awesome Lists containing this project

README 

        
==========

Django-SES

==========

:Info: A Django email backend for Amazon's Simple Email Service

:Author: Harry Marr (http://github.com/hmarr, http://twitter.com/harrymarr)

:Collaborators: Paul Craciunoiu (http://github.com/pcraciunoiu, http://twitter.com/embrangler)



|pypi| |pypi-downloads| |build| |python| |django|



A bird's eye view

=================

Django-SES is a drop-in mail backend for Django_. Instead of sending emails

through a traditional SMTP mail server, Django-SES routes email through

Amazon Web Services' excellent Simple Email Service (SES_).



Please Contribute!

==================

This project is maintained, but not actively used by the maintainer. Interested

in helping maintain this project? Reach out via GitHub Issues if you're actively

using `django-ses` and would be interested in contributing to it.



Changelog

=========



For details about each release, see the GitHub releases page: https://github.com/django-ses/django-ses/releases or CHANGES.md.



Using Django directly

=====================



Amazon SES allows you to also setup usernames and passwords. If you do configure

things that way, you do not need this package. The Django default email backend

is capable of authenticating with Amazon SES and correctly sending email.



Using django-ses gives you additional features like deliverability reports that

can be hard and/or cumbersome to obtain when using the SMTP interface.



Why SES instead of SMTP?

========================

Configuring, maintaining, and dealing with some complicated edge cases can be

time-consuming. Sending emails with Django-SES might be attractive to you if:



* You don't want to maintain mail servers.

* You are already deployed on EC2 (In-bound traffic to SES is free from EC2

  instances).

* You need to send a high volume of email.

* You don't want to have to worry about PTR records, Reverse DNS, email

  whitelist/blacklist services.

* You want to improve delivery rate and inbox cosmetics by DKIM signing

  your messages using SES's Easy DKIM feature.

* Django-SES is a truely drop-in replacement for the default mail backend.

  Your code should require no changes.



Getting going

=============

Assuming you've got Django_ installed, you'll just need to install django-ses::



    pip install django-ses



To receive bounces or webhook events install the events "extra"::



    pip install django-ses[events]



Add the following to your settings.py::



    EMAIL_BACKEND = 'django_ses.SESBackend'



    # These are optional if you are using AWS IAM Roles https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html

    AWS_ACCESS_KEY_ID = 'YOUR-ACCESS-KEY-ID'

    AWS_SECRET_ACCESS_KEY = 'YOUR-SECRET-ACCESS-KEY'

    # https://docs.aws.amazon.com/cli/v1/userguide/cli-configure-files.html

    AWS_SESSION_PROFILE = 'YOUR-PROFILE-NAME'

    # Additionally, if you are not using the default AWS region of us-east-1,

    # you need to specify a region, like so:

    AWS_SES_REGION_NAME = 'us-west-2'

    AWS_SES_REGION_ENDPOINT = 'email.us-west-2.amazonaws.com'



    # If you want to use the SESv2 client

    USE_SES_V2 = True



Alternatively, instead of `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`, you

can include the following two settings values. This is useful in situations

where you would like to use a separate access key to send emails via SES than

you would to upload files via S3::



    AWS_SES_ACCESS_KEY_ID = 'YOUR-ACCESS-KEY-ID'

    AWS_SES_SECRET_ACCESS_KEY = 'YOUR-SECRET-ACCESS-KEY'



Now, when you use ``django.core.mail.send_mail``, Simple Email Service will

send the messages by default.



Since SES imposes a rate limit and will reject emails after the limit has been

reached, django-ses will attempt to conform to the rate limit by querying the

API for your current limit and then sending no more than that number of

messages in a two-second period (which is half of the rate limit, just to

be sure to stay clear of the limit). This is controlled by the following setting:



    AWS_SES_AUTO_THROTTLE = 0.5 # (default; safety factor applied to rate limit)



To turn off automatic throttling, set this to None.



Check out the ``example`` directory for more information.



Monitoring email status using Amazon Simple Notification Service (Amazon SNS)

=============================================================================

To set this up, install `django-ses` with the `events` extra::



    pip install django-ses[events]



Then add a event url handler in your `urls.py`::



    from django.urls import re_path

    from django_ses.views import SESEventWebhookView

    from django.views.decorators.csrf import csrf_exempt

    urlpatterns = [ ...

            re_path(r'^ses/event-webhook/$', SESEventWebhookView.as_view(), name='handle-event-webhook'),

            ...

    ]



SESEventWebhookView handles bounce, complaint, send, delivery, open and click events.

It is also capable of auto confirming subscriptions, it handles `SubscriptionConfirmation` notification.



On AWS

-------

1. Add an SNS topic.



2. In SES setup an SNS destination in "Configuration Sets". Use this

configuration set by setting ``AWS_SES_CONFIGURATION_SET``. Set the topic

to what you created in 1.



3. Add an https subscriber to the topic. (eg. https://www.yourdomain.com/ses/event-webhook/)

Do not check "Enable raw message delivery".



Bounces

-------

Using signal 'bounce_received' for manager bounce email. For example::



    from django_ses.signals import bounce_received

    from django.dispatch import receiver



    @receiver(bounce_received)

    def bounce_handler(sender, mail_obj, bounce_obj, raw_message, *args, **kwargs):

        # you can then use the message ID and/or recipient_list(email address) to identify any problematic email messages that you have sent

        message_id = mail_obj['messageId']

        recipient_list = mail_obj['destination']

        ...

        print("This is bounce email object")

        print(mail_obj)



The most common use case for irrecoverable bounces (status ``5xx``) is to add the

email(s) that caused the bounce to a blacklist in order to avoid sending more

emails and triggering more bounces. ``django-ses`` provides a builtin blacklist

that does this. Check ``AWS_SES_ADD_BOUNCE_TO_BLACKLIST`` and ``AWS_SES_USE_BLACKLIST``.



Complaint

---------

Using signal 'complaint_received' for manager complaint email. For example::



    from django_ses.signals import complaint_received

    from django.dispatch import receiver



    @receiver(complaint_received)

    def complaint_handler(sender, mail_obj, complaint_obj, raw_message,  *args, **kwargs):

        ...



The most common use case for complaints is to add the email(s) that caused the

complaint to a blacklist in order to avoid sending more emails and triggering

more complaints. ``django-ses`` provides a builtin blacklist that does this.

Check ``AWS_SES_ADD_COMPLAINT_TO_BLACKLIST`` and ``AWS_SES_USE_BLACKLIST``.



Send

----

Using signal 'send_received' for manager send email. For example::



    from django_ses.signals import send_received

    from django.dispatch import receiver



    @receiver(send_received)

    def send_handler(sender, mail_obj, raw_message,  *args, **kwargs):

        ...



Delivery

--------

Using signal 'delivery_received' for manager delivery email. For example::



    from django_ses.signals import delivery_received

    from django.dispatch import receiver



    @receiver(delivery_received)

    def delivery_handler(sender, mail_obj, delivery_obj, raw_message,  *args, **kwargs):

        ...



Open

----

Using signal 'open_received' for manager open email. For example::



    from django_ses.signals import open_received

    from django.dispatch import receiver



    @receiver(open_received)

    def open_handler(sender, mail_obj, open_obj, raw_message, *args, **kwargs):

        ...



Click

-----

Using signal 'click_received' for manager send email. For example::



    from django_ses.signals import click_received

    from django.dispatch import receiver



    @receiver(click_received)

    def click_handler(sender, mail_obj, click_obj, raw_message, *args, **kwargs):

        ...



Testing Signals

===============



If you would like to test your signals, you can optionally disable `AWS_SES_VERIFY_EVENT_SIGNATURES` in settings. Examples for the JSON object AWS SNS sends can be found here: https://docs.aws.amazon.com/sns/latest/dg/sns-message-and-json-formats.html#http-subscription-confirmation-json



SES Event Monitoring with Configuration Sets

============================================



You can track your SES email sending at a granular level using `SES Event Publishing`_.

To do this, you set up an SES Configuration Set and add event

handlers to it to send your events on to a destination within AWS (SNS,

Cloudwatch or Kinesis Firehose) for further processing and analysis.



To ensure that emails you send via `django-ses` will be tagged with your

SES Configuration Set, set the `AWS_SES_CONFIGURATION_SET` setting in your

settings.py to the name of the configuration set::



    AWS_SES_CONFIGURATION_SET = 'my-configuration-set-name'



This will add the `X-SES-CONFIGURATION-SET` header to all your outgoing

e-mails.



If you want to set the SES Configuration Set on a per message basis, set

`AWS_SES_CONFIGURATION_SET` to a callable.  The callable should conform to the

following prototype::



    def ses_configuration_set(message, dkim_domain=None, dkim_key=None,

                                dkim_selector=None, dkim_headers=()):

        configuration_set = 'my-default-set'

        # use message and dkim_* to modify configuration_set

        return configuration_set



    AWS_SES_CONFIGURATION_SET = ses_configuration_set



where



* `message` is a `django.core.mail.EmailMessage` object (or subclass)

* `dkim_domain` is a string containing the DKIM domain for this message

* `dkim_key` is a string containing the DKIM private key for this message

* `dkim_selector` is a string containing the DKIM selector (see DKIM, below for

  explanation)

* `dkim_headers` is a list of strings containing the names of the headers to

  be DKIM signed (see DKIM, below for explanation)



DKIM

====



Using DomainKeys_ is entirely optional, however it is recommended by Amazon for

authenticating your email address and improving delivery success rate.  See

http://docs.amazonwebservices.com/ses/latest/DeveloperGuide/DKIM.html.

Besides authentication, you might also want to consider using DKIM in order to

remove the `via email-bounces.amazonses.com` message shown to gmail users -

see http://support.google.com/mail/bin/answer.py?hl=en&answer=1311182.



Currently there are two methods to use DKIM with Django-SES: traditional Manual

Signing and the more recently introduced Amazon Easy DKIM feature.



Easy DKIM

---------

Easy DKIM is a feature of Amazon SES that automatically signs every message

that you send from a verified email address or domain with a DKIM signature.



You can enable Easy DKIM in the AWS Management Console for SES. There you can

also add the required domain verification and DKIM records to Route 53 (or

copy them to your alternate DNS).



Once enabled and verified Easy DKIM needs no additional dependencies or

DKIM specific settings to work with Django-SES.



For more information and a setup guide see:

http://docs.aws.amazon.com/ses/latest/DeveloperGuide/easy-dkim.html



Manual DKIM Signing

-------------------

To enable Manual DKIM Signing you should install the pydkim_ package and specify values

for the ``DKIM_PRIVATE_KEY`` and ``DKIM_DOMAIN`` settings.  You can generate a

private key with a command such as ``openssl genrsa 512`` and get the public key

portion with ``openssl rsa -pubout `_



#. Write and run tests.

    Write your own test showing the issue has been resolved, or the feature

    works as intended.



Git hooks (via pre-commit)

==========================



We use pre-push hooks to ensure that only linted code reaches our remote repository and pipelines aren't triggered in

vain.



To enable the configured pre-push hooks, you need to [install](https://pre-commit.com/) pre-commit and run once::



    pre-commit install -t pre-push -t pre-commit --install-hooks



This will permanently install the git hooks for both, frontend and backend, in your local

[`.git/hooks`](./.git/hooks) folder.

The hooks are configured in the [`.pre-commit-config.yaml`](.pre-commit-config.yaml).



You can check whether hooks work as intended using the [run](https://pre-commit.com/#pre-commit-run) command::



    pre-commit run [hook-id] [options]



Example: run single hook::



    pre-commit run ruff --all-files --hook-stage push



Example: run all hooks of pre-push stage::



    pre-commit run --all-files --hook-stage push



Running Tests

=============

To run the tests::



    python runtests.py



If you want to debug the tests, just add this file as a python script to your IDE run configuration.



Creating a Release

==================



To create a release:



* Run ``poetry version {patch|minor|major}`` as explained in `the docs `_. This will update the version in pyproject.toml.

* Commit that change and use git to tag that commit with a version that matches the pattern ``v*.*.*``.

* Push the tag and the commit (note some IDEs don't push tags by default).



.. |pypi| image:: https://badge.fury.io/py/django-ses.svg

    :target: http://badge.fury.io/py/django-ses

.. |pypi-downloads| image:: https://img.shields.io/pypi/dm/django-ses?style=flat

    :target: https://pypi.org/project/django-ses/

.. |build| image:: https://github.com/django-ses/django-ses/actions/workflows/ci.yml/badge.svg

    :target: https://github.com/django-ses/django-ses/actions/workflows/ci.yml

.. |python| image:: https://img.shields.io/badge/python-3.8|3.9|3.10|3.11|3.12-blue.svg

    :target: https://pypi.org/project/django-ses/

.. |django| image:: https://img.shields.io/badge/django-4.2%7C%205.0+-blue.svg

    :target: https://www.djangoproject.com/