public
/
django_aws_ses
7
0
Fork 0
Code Issues 2 Pull Requests Packages Projects Releases Wiki Activity

re work of readme

This commit is contained in:
Raymond Jessop 2025-04-22 21:25:03 -05:00
parent eb088fa119
commit 1505196781
1 changed files with 154 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

191
README.md
View File

@ -3,9 +3,10 @@
A Django email backend for Amazon Simple Email Service (SES), featuring bounce and complaint handling, unsubscribe functionality, and robust integration with Django’s email system. Developed by ZeeksGeeks. A Django email backend for Amazon Simple Email Service (SES), featuring bounce and complaint handling, unsubscribe functionality, and robust integration with Django’s email system. Developed by ZeeksGeeks.
## Features ## Features
- Seamless integration with Django’s email framework using a custom SES backend. - Seamless integration with Django’s email framework using a custom SES backend.
- Handles AWS SES bounce and complaint notifications via SNS. - Handles AWS SES bounce and complaint notifications via SNS.
- Secure unsubscriptions fuctionality. - Secure unsubscribe functionality.
- Django Admin dashboard for SES statistics. - Django Admin dashboard for SES statistics.
- (Optional) Supports DKIM signing, requires `dkimpy`. - (Optional) Supports DKIM signing, requires `dkimpy`.
@ -14,6 +15,7 @@ A Django email backend for Amazon Simple Email Service (SES), featuring bounce a
Follow these steps to install and configure `django_aws_ses` in your Django project. Follow these steps to install and configure `django_aws_ses` in your Django project.
### Prerequisites ### Prerequisites
- Python 3.6 or higher - Python 3.6 or higher
- Django 3.2 or higher - Django 3.2 or higher
- An AWS account with SES access - An AWS account with SES access
@ -21,44 +23,34 @@ Follow these steps to install and configure `django_aws_ses` in your Django proj
### Step 1: Install the Package ### Step 1: Install the Package
Install `django_aws_ses`: Install `django_aws_ses` from PyPI:
```bash ```bash
pip install django_aws_ses pip install django-aws-ses
``` ```
Install `django_aws_ses` from TestPyPI: For development or testing, include development dependencies:
```bash ```bash
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ django_aws_ses pip install django-aws-ses[dev]
``` ```
For production, this installs the core dependencies: For DKIM signing support (optional):
```bash
pip install django-aws-ses[dkim]
```
This installs core dependencies:
- `django>=3.2` - `django>=3.2`
- `boto3>=1.18.0` - `boto3>=1.18.0`
- `requests>=2.26.0` - `requests>=2.26.0`
- `cryptography>=3.4.7` - `cryptography>=3.4.7`
- `dnspython>=2.1.0` - `dnspython>=2.1.0`
For development:
```bash
pip install django_aws_ses[dev]
```
For development or testing, include development dependencies:
```bash
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ django_aws_ses[dev]
```
For DKIM signing support (optional):
```bash
pip install django_aws_ses[dkim]
```
For DKIM signing support (optional):
```bash
pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ django_aws_ses[dkim]
```
### Step 2: Configure Django Settings ### Step 2: Configure Django Settings
Add `django_aws_ses` and required Django apps to `INSTALLED_APPS` in your `settings.py`: Add `django_aws_ses` and required Django apps to `INSTALLED_APPS` in your `settings.py`:
```python ```python
@ -111,6 +103,7 @@ LOGGING = {
``` ```
### Step 3: Set Up URLs ### Step 3: Set Up URLs
Include the `django_aws_ses` URLs in your project’s `urls.py`: Include the `django_aws_ses` URLs in your project’s `urls.py`:
```python ```python
@ -121,9 +114,10 @@ urlpatterns = [
] ]
``` ```
This enables endpoints for bounce/complaint handling (`https://exampl.com/aws_ses/bounce/`) and unsubscribe functionality (`https://exampl.com/aws_ses/unsubscribe/<uuid>/<token>/`). This enables endpoints for bounce/complaint handling (`https://yourdomain.com/aws_ses/bounce/`) and unsubscribe functionality (`https://yourdomain.com/aws_ses/unsubscribe/<uuid>/<token>/`).
### Step 4: Apply Migrations ### Step 4: Apply Migrations
Run migrations to create the `django_aws_ses` models (e.g., `AwsSesSettings`, `BounceRecord`): Run migrations to create the `django_aws_ses` models (e.g., `AwsSesSettings`, `BounceRecord`):
```bash ```bash
@ -131,13 +125,71 @@ python manage.py migrate
``` ```
### Step 5: Configure AWS SES ### Step 5: Configure AWS SES
- **Verify Email/Domain**: In the AWS SES console, verify your sender email (e.g., `no-reply@yourdomain.com`) or domain.
- **SNS Notifications**: Set up an SNS topic to send bounce and complaint notifications to your `https://exampl.com/aws_ses/bounce/` endpoint. Follow these detailed steps to set up Amazon SES in your AWS account for use with `django_aws_ses`:
- **Exit Sandbox Mode** (if needed): Request production access in AWS SES to send emails to unverified recipients.
- **IAM Permissions**: Ensure your IAM user has permissions for SES and SNS (e.g., `AmazonSESFullAccess`). 1. **Sign Up for AWS SES**:
- Log in to the AWS Management Console.
- Navigate to SES: https://console.aws.amazon.com/ses/.
- If new to SES, follow prompts to activate the service.
- Docs: https://docs.aws.amazon.com/ses/latest/dg/get-set-up.html
2. **Verify Sender Email or Domain**:
- In the SES console, go to "Verified identities."
- Click "Create identity":
- **Email Address**: Enter the sender email (e.g., `no-reply@yourdomain.com`). AWS sends a verification email; click the link to verify.
- **Domain**: Enter your domain (e.g., `yourdomain.com`). Add provided DNS records (TXT, CNAME, MX) to your DNS provider to verify ownership.
- Docs: https://docs.aws.amazon.com/ses/latest/dg/creating-identities.html
3. **Create IAM Credentials**:
- Create an IAM user for SES:
- Go to IAM in AWS Console: https://console.aws.amazon.com/iam/.
- Create a user (e.g., `ses-user`) with programmatic access.
- Attach permissions (e.g., `AmazonSESFullAccess` and `AmazonSNSFullAccess`).
- Save the Access Key ID and Secret Access Key for `settings.py`.
- Docs: https://docs.aws.amazon.com/ses/latest/dg/control-user-access.html
4. **Set Up SNS Notifications**:
- Create an SNS topic (e.g., `SES_Notifications`) in the SNS console: https://console.aws.amazon.com/sns/.
- Subscribe your bounce/complaint endpoint (`https://yourdomain.com/aws_ses/bounce/`) to the topic using the HTTPS protocol.
- In SES, go to "Verified identities," select your email/domain, and configure notifications to send bounces, complaints, and deliveries to the SNS topic.
- Docs: https://docs.aws.amazon.com/ses/latest/dg/monitor-using-notifications.html
5. **(Optional) Configure DKIM Signing**:
- If using DKIM, enable it in SES:
- In "Verified identities," select your domain and enable DKIM.
- Add provided DKIM DNS records to your DNS provider.
- Ensure `dkimpy` is installed (`pip install django-aws-ses[dkim]`).
- Docs: https://docs.aws.amazon.com/ses/latest/dg/send-email-authentication-dkim.html
6. **Test SES Configuration**:
- In SES console, send a test email from "Verified identities."
- Verify receipt in the recipient’s inbox.
- Test sending from Django (see Usage).
- Docs: https://docs.aws.amazon.com/ses/latest/dg/send-an-email.html
7. **Exit Sandbox Mode (Production)**:
- SES sandbox mode restricts sending to verified emails only.
- For production, request access:
- Open a support case in AWS Support Center.
- Provide use case (e.g., transactional emails for user registration).
- Approval typically takes 24 hours.
- Docs: https://docs.aws.amazon.com/ses/latest/dg/request-production-access.html
## Usage ## Usage
Send an email using Django’s email API:
`django_aws_ses` integrates with Django’s email API and provides additional features for SES-specific functionality. The following examples are shown in a Python console (e.g., Django shell or within a view).
### Sending a Basic Email
Use Django’s `send_mail` for simple emails:
```python ```python
from django.core.mail import send_mail from django.core.mail import send_mail
@ -145,27 +197,92 @@ from django.core.mail import send_mail
send_mail( send_mail(
subject='Test Email', subject='Test Email',
message='This is a test email from django_aws_ses.', message='This is a test email from django_aws_ses.',
from_email='no-reply@yourdomain.com', from_email='no-reply@yourdomain.com', # Must be SES-verified
recipient_list=['recipient@example.com'], recipient_list=['recipient@example.com'],
fail_silently=False, fail_silently=False,
) )
``` ```
Generate an unsubscribe link for a user: - Set `fail_silently=False` to raise exceptions for debugging (e.g., unverified email errors).
### Sending HTML Emails
Send emails with HTML content and plain text fallback:
```python
from django.core.mail import EmailMultiAlternatives
subject = 'Welcome to Our Platform'
from_email = 'no-reply@yourdomain.com'
to = 'recipient@example.com'
text_content = 'Thank you for joining our platform!'
html_content = '<p>Thank you for joining! <a href="https://yourdomain.com">Visit us</a></p>'
email = EmailMultiAlternatives(subject, text_content, from_email, [to])
email.attach_alternative(html_content, 'text/html')
email.send()
```
### Handling Bounce and Complaint Notifications
- Bounce and complaint notifications are processed via the SNS endpoint (`/aws_ses/bounce/`).
- Records are stored in the `BounceRecord` model.
- View bounce/complaint data in the Django Admin or SES dashboard (`/aws_ses/status/`).
- Configure additional SNS notifications for deliveries in SES console.
- Docs: https://docs.aws.amazon.com/ses/latest/dg/monitor-sending-activity.html
### Generating Unsubscribe Links
Add secure unsubscribe links to emails:
```python ```python
from django_aws_ses.models import AwsSesUserAddon from django_aws_ses.models import AwsSesUserAddon
user = User.objects.get(email='recipient@example.com') user = User.objects.get(email='recipient@example.com')
addon = AwsSesUserAddon.objects.get(user=user) addon = AwsSesUserAddon.objects.get_or_create(user=user)[0]
unsubscribe_url = addon.unsubscribe_url_generator() unsubscribe_url = addon.unsubscribe_url_generator()
# Include unsubscribe_url in your email template # Include in email template, e.g., <a href="{{ unsubscribe_url }}">Unsubscribe</a>
``` ```
View SES statistics (superusers only) at `https://exampl.com/aws_ses/status/`. - Users clicking the link are redirected to `/aws_ses/unsubscribe/<uuid>/<token>/`, which marks them as unsubscribed.
- Customize the unsubscribe view or template in `django_aws_ses/templates/django_aws_ses/unsubscribe.html`.
### Viewing SES Statistics Phelps
- Access the SES dashboard at `/aws_ses/status/` (superusers only).
- Displays bounce rates, complaint rates, and email sending history.
- Uses `BounceRecord` and SES API data for metrics.
- Docs: https://docs.aws.amazon.com/ses/latest/dg/monitor-sending-metrics.html
### Debugging and Error Handling
- Enable debug logging (see Step 2) to troubleshoot SES errors.
- Common issues:
- **Unverified email/domain**: Verify in SES console.
- **IAM permissions**: Ensure `AmazonSESFullAccess` and `AmazonSNSFullAccess`.
- **SNS endpoint errors**: Confirm HTTPS endpoint is publicly accessible.
- Check `BounceRecord` in Django Admin for failed deliveries.
### Rate Limiting and Throttling
- SES imposes sending quotas and rate limits.
- Monitor limits in SES console ("Sending Statistics").
- If approaching limits, request a quota increase:
- Open a support case in AWS Support Center.
- Specify desired sending rate and daily quota.
- Docs: https://docs.aws.amazon.com/ses/latest/dg/manage-sending-limits.html
## Contributors ## Contributors
Developed by the ZeeksGeeks team. See [CONTRIBUTORS.md](CONTRIBUTORS.md) for individual contributors and their roles.
Developed by the ZeeksGeeks team. See CONTRIBUTORS.md for individual contributors and their roles.
## License ## License
This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.
This project is licensed under the MIT License. See LICENSE for details.
## PyPI Distribution
- Install: `pip install django-aws-ses`
- Source: https://git-vault.zeeksgeeks.com/public/django_aws_ses
- Issues: https://git-vault.zeeksgeeks.com/public/django_aws_ses/issues
- PyPI: https://pypi.org/project/django-aws-ses/