From 1505196781a6031f1036f0723f570c93fb681796 Mon Sep 17 00:00:00 2001 From: Raymond Jessop Date: Tue, 22 Apr 2025 21:25:03 -0500 Subject: [PATCH] re work of readme --- README.md | 191 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 154 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index f8c2637..c421e21 100644 --- a/README.md +++ b/README.md @@ -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. ## Features + - Seamless integration with Django’s email framework using a custom SES backend. - Handles AWS SES bounce and complaint notifications via SNS. -- Secure unsubscriptions fuctionality. +- Secure unsubscribe functionality. - Django Admin dashboard for SES statistics. - (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. ### Prerequisites + - Python 3.6 or higher - Django 3.2 or higher - 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 -Install `django_aws_ses`: +Install `django_aws_ses` from PyPI: ```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 -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` - `boto3>=1.18.0` - `requests>=2.26.0` - `cryptography>=3.4.7` - `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 + Add `django_aws_ses` and required Django apps to `INSTALLED_APPS` in your `settings.py`: ```python @@ -111,6 +103,7 @@ LOGGING = { ``` ### Step 3: Set Up URLs + Include the `django_aws_ses` URLs in your project’s `urls.py`: ```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///`). +This enables endpoints for bounce/complaint handling (`https://yourdomain.com/aws_ses/bounce/`) and unsubscribe functionality (`https://yourdomain.com/aws_ses/unsubscribe///`). ### Step 4: Apply Migrations + Run migrations to create the `django_aws_ses` models (e.g., `AwsSesSettings`, `BounceRecord`): ```bash @@ -131,13 +125,71 @@ python manage.py migrate ``` ### 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. -- **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`). + +Follow these detailed steps to set up Amazon SES in your AWS account for use with `django_aws_ses`: + +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 -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 from django.core.mail import send_mail @@ -145,27 +197,92 @@ from django.core.mail import send_mail send_mail( subject='Test Email', 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'], 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 = '

Thank you for joining! Visit us

' + +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 from django_aws_ses.models import AwsSesUserAddon 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() -# Include unsubscribe_url in your email template +# Include in email template, e.g., Unsubscribe ``` -View SES statistics (superusers only) at `https://exampl.com/aws_ses/status/`. +- Users clicking the link are redirected to `/aws_ses/unsubscribe///`, 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 -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 -This project is licensed under the MIT License. See [LICENSE](LICENSE) for details. \ No newline at end of file + +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/ \ No newline at end of file