# django-ses-backend
Django AWS SES (Amazon Simple Email Service) email backend.
## Features
- Send emails via AWS SES without needing `boto3` or any other AWS SDK.
- No SMTP configuration required and faster email sending.
- Supports sending plain text and HTML emails, including multi-part messages.
- Lightweight and easy to integrate.
- Supports Django's `EmailMessage` and `EmailMultiAlternatives`.
- Handles `Reply-To` and custom headers.
- Custom SES client implementation with AWS signature v4, rate-limit retries, and exponential backoff.
- Context manager support for use with `with SESEmailBackend() as connection:`.
## Requirements
- Python 3.11+
- Django 4.2+
## Installation
Install the package using pip:
```bash
pip install django-ses-backend
```
[PyPi.com](https://pypi.org/project/django-ses-backend/)
## AWS Setup
### Step 1: Create an AWS SES Account
1. Sign in to the [AWS Management Console](https://aws.amazon.com/console/).
2. Navigate to **Amazon SES** service.
3. Verify your email address or domain in the **Verified Identities** section.
4. Move your SES account out of **Sandbox Mode** (if needed) by requesting production access.
### Step 2: Create an IAM User for SES
1. Go to **IAM** in the AWS Console.
2. Create a new user and enable **Programmatic access**.
3. Attach the policy **AmazonSESFullAccess** (or a custom policy with `ses:SendEmail` permissions).
4. Save the **Access Key ID** and **Secret Access Key**.
## Configuration
Update your Django settings:
```python
# settings.py
EMAIL_BACKEND = 'django_ses_backend.backends.SESEmailBackend'
SES_AWS_ACCESS_KEY_ID = 'YOUR_AWS_ACCESS_KEY_ID'
SES_AWS_SECRET_ACCESS_KEY = 'YOUR_AWS_SECRET_ACCESS_KEY'
SES_AWS_REGION = 'YOUR_AWS_REGION'
# Optional advanced settings
SES_ENDPOINT_URL = None # Custom endpoint URL
SES_ENDPOINT_PATH = None # Custom endpoint path
SES_TIMEOUT = 10 # HTTP request timeout in seconds
SES_MAX_RETRIES = 3 # Max retry attempts for rate-limits/server errors
SES_RETRY_DELAY = 1.0 # Base delay (seconds) for exponential backoff
```
## Usage
You can send emails using Django's built-in `send_mail` or `EmailMessage`:
```python
from django.core.mail import send_mail
send_mail(
subject="Hello from AWS SES",
message="This is a test email.",
from_email="your-email@example.com",
recipient_list=["recipient@example.com"],
)
```
Or using `EmailMessage` for more customization:
```python
from django.core.mail import EmailMessage
email = EmailMessage(
subject="Hello from AWS SES",
body="This is a test email.",
from_email="your-email@example.com",
to=["recipient@example.com"],
)
email.send()
```
### Sending HTML Emails
Supports both HTML and text content:
```python
from django.core.mail import EmailMultiAlternatives
email = EmailMultiAlternatives(
subject="HTML Email Test",
body="Fallback plain text content",
from_email="your-email@example.com",
to=["recipient@example.com"],
)
email.attach_alternative("<h1>Hello from AWS SES</h1>", "text/html")
email.send()
```
### Handling Reply-To and Custom Headers
```python
email = EmailMessage(
subject="Email with Reply-To",
body="Hello",
from_email="your-email@example.com",
to=["recipient@example.com"],
reply_to=["replyto@example.com"],
headers={"Message-ID": "<custom.id@example.com>"},
)
email.send()
```
## Error Handling
* `SESClientError` is raised for generic sending failures.
* `SESRatelimitError` is raised when AWS rate-limits are hit.
* Retries are performed automatically with exponential backoff for 429/5xx errors.
```python
try:
email.send()
except SESClientError as e:
print(f"Failed to send email: {e}")
```
## Logging
Enable logging to track email sending:
```python
import logging
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger("django_ses_backend")
```
## Notes
* Always include both text and HTML versions for best deliverability.
* Attachments are ignored by this backend.
* Ensure your AWS SES account is verified and out of sandbox mode.
* Configure AWS IAM policies to grant `ses:SendEmail` permissions.
## Contributing
Feel free to submit issues or pull requests on GitHub to improve this package.
Raw data
{
"_id": null,
"home_page": "https://github.com/almazkun/django-ses-backend",
"name": "django-ses-backend",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "django, email, aws, ses, backend",
"author": "Almaz Kunpeissov",
"author_email": "hello@akun.dev",
"download_url": "https://files.pythonhosted.org/packages/c9/13/948e3ef0d48482b39122a4a83971a21077b8b63f13c7472b0dcd18efb2b4/django_ses_backend-0.1.2.tar.gz",
"platform": null,
"description": "# django-ses-backend\n\nDjango AWS SES (Amazon Simple Email Service) email backend.\n\n## Features\n- Send emails via AWS SES without needing `boto3` or any other AWS SDK.\n- No SMTP configuration required and faster email sending.\n- Supports sending plain text and HTML emails, including multi-part messages.\n- Lightweight and easy to integrate.\n- Supports Django's `EmailMessage` and `EmailMultiAlternatives`.\n- Handles `Reply-To` and custom headers.\n- Custom SES client implementation with AWS signature v4, rate-limit retries, and exponential backoff.\n- Context manager support for use with `with SESEmailBackend() as connection:`.\n\n## Requirements\n- Python 3.11+\n- Django 4.2+\n\n## Installation\n\nInstall the package using pip:\n\n\n```bash\npip install django-ses-backend\n```\n[PyPi.com](https://pypi.org/project/django-ses-backend/)\n\n## AWS Setup\n\n### Step 1: Create an AWS SES Account\n\n1. Sign in to the [AWS Management Console](https://aws.amazon.com/console/).\n2. Navigate to **Amazon SES** service.\n3. Verify your email address or domain in the **Verified Identities** section.\n4. Move your SES account out of **Sandbox Mode** (if needed) by requesting production access.\n\n### Step 2: Create an IAM User for SES\n\n1. Go to **IAM** in the AWS Console.\n2. Create a new user and enable **Programmatic access**.\n3. Attach the policy **AmazonSESFullAccess** (or a custom policy with `ses:SendEmail` permissions).\n4. Save the **Access Key ID** and **Secret Access Key**.\n\n## Configuration\n\nUpdate your Django settings:\n\n```python\n# settings.py\nEMAIL_BACKEND = 'django_ses_backend.backends.SESEmailBackend'\n\nSES_AWS_ACCESS_KEY_ID = 'YOUR_AWS_ACCESS_KEY_ID'\nSES_AWS_SECRET_ACCESS_KEY = 'YOUR_AWS_SECRET_ACCESS_KEY'\nSES_AWS_REGION = 'YOUR_AWS_REGION'\n\n# Optional advanced settings\nSES_ENDPOINT_URL = None # Custom endpoint URL\nSES_ENDPOINT_PATH = None # Custom endpoint path\nSES_TIMEOUT = 10 # HTTP request timeout in seconds\nSES_MAX_RETRIES = 3 # Max retry attempts for rate-limits/server errors\nSES_RETRY_DELAY = 1.0 # Base delay (seconds) for exponential backoff\n```\n\n## Usage\n\nYou can send emails using Django's built-in `send_mail` or `EmailMessage`:\n\n```python\nfrom django.core.mail import send_mail\n\nsend_mail(\n subject=\"Hello from AWS SES\",\n message=\"This is a test email.\",\n from_email=\"your-email@example.com\",\n recipient_list=[\"recipient@example.com\"],\n)\n```\n\nOr using `EmailMessage` for more customization:\n\n```python\nfrom django.core.mail import EmailMessage\n\nemail = EmailMessage(\n subject=\"Hello from AWS SES\",\n body=\"This is a test email.\",\n from_email=\"your-email@example.com\",\n to=[\"recipient@example.com\"],\n)\nemail.send()\n```\n\n### Sending HTML Emails\n\nSupports both HTML and text content:\n\n```python\nfrom django.core.mail import EmailMultiAlternatives\n\nemail = EmailMultiAlternatives(\n subject=\"HTML Email Test\",\n body=\"Fallback plain text content\",\n from_email=\"your-email@example.com\",\n to=[\"recipient@example.com\"],\n)\nemail.attach_alternative(\"<h1>Hello from AWS SES</h1>\", \"text/html\")\nemail.send()\n```\n\n### Handling Reply-To and Custom Headers\n\n```python\nemail = EmailMessage(\n subject=\"Email with Reply-To\",\n body=\"Hello\",\n from_email=\"your-email@example.com\",\n to=[\"recipient@example.com\"],\n reply_to=[\"replyto@example.com\"],\n headers={\"Message-ID\": \"<custom.id@example.com>\"},\n)\nemail.send()\n```\n\n## Error Handling\n\n* `SESClientError` is raised for generic sending failures.\n* `SESRatelimitError` is raised when AWS rate-limits are hit.\n* Retries are performed automatically with exponential backoff for 429/5xx errors.\n\n```python\ntry:\n email.send()\nexcept SESClientError as e:\n print(f\"Failed to send email: {e}\")\n```\n\n## Logging\n\nEnable logging to track email sending:\n\n```python\nimport logging\n\nlogging.basicConfig(level=logging.DEBUG)\nlogger = logging.getLogger(\"django_ses_backend\")\n```\n\n## Notes\n\n* Always include both text and HTML versions for best deliverability.\n* Attachments are ignored by this backend.\n* Ensure your AWS SES account is verified and out of sandbox mode.\n* Configure AWS IAM policies to grant `ses:SendEmail` permissions.\n\n## Contributing\n\nFeel free to submit issues or pull requests on GitHub to improve this package.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Django email backend for AWS SES (Amazon Simple Email Service) without boto3",
"version": "0.1.2",
"project_urls": {
"Bug Tracker": "https://github.com/akun/django-ses-backend/issues",
"Documentation": "https://github.com/almazkun/django-ses-backend#readme",
"Homepage": "https://github.com/almazkun/django-ses-backend",
"Repository": "https://github.com/almazkun/django-ses-backend",
"changelog": "https://github.com/almazkun/django-ses-backend/blob/main/CHANGELOG.md"
},
"split_keywords": [
"django",
" email",
" aws",
" ses",
" backend"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7140a66f7767f6c273bf62876151a22353e1adfd3dd5818efd52dde1322c75d0",
"md5": "e139758b638df4f227c9f770954a6d1e",
"sha256": "4399e9d4dbb99914d54170620c1845b4aac62b69cc2c715e5895e5f6e392488b"
},
"downloads": -1,
"filename": "django_ses_backend-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e139758b638df4f227c9f770954a6d1e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 7575,
"upload_time": "2025-09-12T01:53:07",
"upload_time_iso_8601": "2025-09-12T01:53:07.202392Z",
"url": "https://files.pythonhosted.org/packages/71/40/a66f7767f6c273bf62876151a22353e1adfd3dd5818efd52dde1322c75d0/django_ses_backend-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c913948e3ef0d48482b39122a4a83971a21077b8b63f13c7472b0dcd18efb2b4",
"md5": "f6a094d28079f003070911f07d295a38",
"sha256": "c06ce73c39aa02e6badc49771b3658e965a2cc1be8f17c2e1cc02cd783abd8b1"
},
"downloads": -1,
"filename": "django_ses_backend-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "f6a094d28079f003070911f07d295a38",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 6807,
"upload_time": "2025-09-12T01:53:08",
"upload_time_iso_8601": "2025-09-12T01:53:08.652791Z",
"url": "https://files.pythonhosted.org/packages/c9/13/948e3ef0d48482b39122a4a83971a21077b8b63f13c7472b0dcd18efb2b4/django_ses_backend-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-12 01:53:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "almazkun",
"github_project": "django-ses-backend",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"tox": true,
"lcname": "django-ses-backend"
}
JSON
