Django SES Email Backend

4.7.2 · active · verified Sat Apr 11

django-ses is a Django email backend that integrates with Amazon's Simple Email Service (SES), offering a reliable and scalable way to send emails. It acts as a drop-in replacement for Django's default email backend, routing emails through AWS SES instead of traditional SMTP. The library, currently at version 4.7.2, is actively maintained with frequent releases to support new Django and Python versions, address bugs, and introduce new features like bounce/complaint handling and email receiving capabilities.

Warnings

deprecated Django 3.2 support was temporarily removed in v4.7.0 and re-added in v4.7.1, but the project maintainers plan to drop support for Django 3.2 as it is no longer officially supported by Django itself.
Fix: Upgrade your Django project to a currently supported version (e.g., Django 4.2+ or 5.0+) to ensure ongoing compatibility and support for django-ses.
gotcha AWS SES operates in a 'sandbox' mode by default for new accounts, restricting email sending to only verified email addresses or domains. To send emails to any recipient, you must request production access from AWS.
Fix: Apply for production access in the AWS SES console. Ensure all sender email addresses and domains are verified within AWS SES.
gotcha AWS credentials (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY) should never be hardcoded directly in your settings.py. This is a security risk.
Fix: Store credentials in environment variables (e.g., via `os.environ`), use an IAM role if deployed on AWS EC2/Lambda, or leverage AWS CLI profiles. Remove hardcoded credentials from your source code.
gotcha The automatic bounce and complaint handling features (introduced in v4.2.0) and email receiving features (v4.3.0) require specific configuration (e.g., SNS topic, handler classes) and may involve database migrations. If not configured, these features will not work.
Fix: Consult the official django-ses documentation for detailed setup instructions for bounce/complaint handling and email receiving if you intend to use these features. Ensure you run `python manage.py migrate` if using the blacklist models.
gotcha When using `django_ses.SESBackend`, the library interacts with the SES API, not the SES SMTP endpoint. If you specifically require SMTP for AWS SES, you should use Django's built-in `django.core.mail.backends.smtp.EmailBackend` and configure it with SES SMTP credentials.
Fix: For API-based sending with additional features, use `django_ses.SESBackend`. For direct SMTP, configure `EMAIL_BACKEND = 'django.core.mail.backends.smtp.EmailBackend'` and provide the appropriate SES SMTP `EMAIL_HOST`, `EMAIL_HOST_USER`, and `EMAIL_HOST_PASSWORD` settings.

Install

pip install django-ses Install stable version

Imports

SESBackend
```
EMAIL_BACKEND = 'django_ses.SESBackend'
```
Used in Django's settings.py to specify the email backend.

Quickstart

Configure your Django `settings.py` to use `django_ses.SESBackend` and set your AWS credentials and region. It is highly recommended to manage `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_SES_REGION_NAME` via environment variables or IAM roles for security. Ensure `DEFAULT_FROM_EMAIL` is set to an address or domain verified in AWS SES. Then, use Django's standard `send_mail` function to send emails.

import os
from django.core.mail import send_mail

# Ensure these are set in your Django settings.py
# EMAIL_BACKEND = 'django_ses.SESBackend'
# AWS_ACCESS_KEY_ID = os.environ.get('AWS_ACCESS_KEY_ID', '')
# AWS_SECRET_ACCESS_KEY = os.environ.get('AWS_SECRET_ACCESS_KEY', '')
# AWS_SES_REGION_NAME = os.environ.get('AWS_SES_REGION_NAME', 'us-east-1')
# DEFAULT_FROM_EMAIL = 'verified-sender@example.com'

# Example of sending a simple email
if os.environ.get('AWS_ACCESS_KEY_ID') and os.environ.get('AWS_SECRET_ACCESS_KEY'):
    try:
        send_mail(
            'Subject here',
            'Here is the message body.',
            os.environ.get('DEFAULT_FROM_EMAIL', 'test@example.com'),
            ['recipient@example.com'],
            fail_silently=False,
        )
        print("Email sent successfully!")
    except Exception as e:
        print(f"Failed to send email: {e}")
else:
    print("AWS credentials not set in environment variables. Cannot send email.")

view raw JSON →