added changelog to readme

This commit is contained in:
Raymond Jessop 2025-04-22 23:15:53 -05:00
parent 922392a332
commit 95323c0c78
1 changed files with 33 additions and 37 deletions

View File

@ -4,34 +4,34 @@ A Django email backend for Amazon Simple Email Service (SES), featuring bounce a
## Table of Contents ## Table of Contents
- Features - [Features](#features)
- Installation - [Installation](#installation)
- Prerequisites - [Prerequisites](#prerequisites)
- Step 1: Install the Package - [Step 1: Install the Package](#step-1-install-the-package)
- Step 2: Configure Django Settings - [Step 2: Configure Django Settings](#step-2-configure-django-settings)
- Step 3: Set Up URLs - [Step 3: Set Up URLs](#step-3-set-up-urls)
- Step 4: Apply Migrations - [Step 4: Apply Migrations](#step-4-apply-migrations)
- Step 5: Configure AWS SES - [Step 5: Configure AWS SES](#step-5-configure-aws-ses)
- Usage - [Usage](#usage)
- Sending a Basic Email - [Sending a Basic Email](#sending-a-basic-email)
- Sending HTML Emails - [Sending HTML Emails](#sending-html-emails)
- Handling Bounce and Complaint Notifications - [Handling Bounce and Complaint Notifications](#handling-bounce-and-complaint-notifications)
- Generating Unsubscribe Links - [Generating Unsubscribe Links](#generating-unsubscribe-links)
- Viewing SES Statistics - [Viewing SES Statistics](#viewing-ses-statistics)
- Debugging and Error Handling - [Debugging and Error Handling](#debugging-and-error-handling)
- Rate Limiting and Throttling - [Rate Limiting and Throttling](#rate-limiting-and-throttling)
- Changelog - [Changelog](#changelog)
- Contributors - [Contributors](#contributors)
- License - [License](#license)
- PyPI Distribution - [PyPI Distribution](#pypi-distribution)
## Features ## Features
- Seamless integration with Djangos email framework using a custom SES backend. - Seamless integration with Djangos 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 unsubscribe functionality with non-expiring links and GET/POST protection. - Secure unsubscribe functionality.
- Django Admin dashboard for SES statistics (superusers only). - Django Admin dashboard for SES statistics.
- Optional DKIM signing support (requires `dkimpy`). - (Optional) Supports DKIM signing, requires `dkimpy`.
## Installation ## Installation
@ -141,7 +141,7 @@ This enables endpoints for bounce/complaint handling (`https://yourdomain.com/aw
### Step 4: Apply Migrations ### Step 4: Apply Migrations
Run migrations to create the `django_aws_ses` models (e.g., `AwsSesSettings`, `BounceRecord`, `ComplaintRecord`, `SendRecord`, `AwsSesUserAddon`): Run migrations to create the `django_aws_ses` models (e.g., `AwsSesSettings`, `BounceRecord`):
```bash ```bash
python manage.py migrate python manage.py migrate
@ -249,7 +249,7 @@ email.send()
### Handling Bounce and Complaint Notifications ### Handling Bounce and Complaint Notifications
- Bounce and complaint notifications are processed via the SNS endpoint (`/aws_ses/bounce/`). - Bounce and complaint notifications are processed via the SNS endpoint (`/aws_ses/bounce/`).
- Records are stored in the `BounceRecord` and `ComplaintRecord` models. - Records are stored in the `BounceRecord` model.
- View bounce/complaint data in the Django Admin or SES dashboard (`/aws_ses/status/`). - View bounce/complaint data in the Django Admin or SES dashboard (`/aws_ses/status/`).
- Configure additional SNS notifications for deliveries in SES console. - Configure additional SNS notifications for deliveries in SES console.
- Docs: https://docs.aws.amazon.com/ses/latest/dg/monitor-sending-activity.html - Docs: https://docs.aws.amazon.com/ses/latest/dg/monitor-sending-activity.html
@ -270,23 +270,21 @@ unsubscribe_url = addon.unsubscribe_url_generator()
- Users clicking the link are redirected to `/aws_ses/unsubscribe/<uuid>/<token>/`, which marks them as unsubscribed. - 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`. - Customize the unsubscribe view or template in `django_aws_ses/templates/django_aws_ses/unsubscribe.html`.
### Viewing SES Statistics ### Viewing SES Statistics Phelps
- Access the SES dashboard at `/aws_ses/status/` (superusers only). - Access the SES dashboard at `/aws_ses/status/` (superusers only).
- Displays bounce rates, complaint rates, and email sending history. - Displays bounce rates, complaint rates, and email sending history.
- Uses `BounceRecord`, `ComplaintRecord`, and `SendRecord` models for metrics. - Uses `BounceRecord` and SES API data for metrics.
- Docs: https://docs.aws.amazon.com/ses/latest/dg/monitor-sending-metrics.html - Docs: https://docs.aws.amazon.com/ses/latest/dg/monitor-sending-metrics.html
### ### Debugging and Error Handling
System: Debugging and Error Handling
- Enable debug logging (see Step 2) to troubleshoot SES errors. - Enable debug logging (see Step 2) to troubleshoot SES errors.
- Common issues: - Common issues:
- **Unverified email/domain**: Verify in SES console. - **Unverified email/domain**: Verify in SES console.
- **IAM permissions**: Ensure `AmazonSESFullAccess` and `AmazonSNSFullAccess`. - **IAM permissions**: Ensure `AmazonSESFullAccess` and `AmazonSNSFullAccess`.
- **SNS endpoint errors**: Confirm HTTPS endpoint is publicly accessible. - **SNS endpoint errors**: Confirm HTTPS endpoint is publicly accessible.
- Check `BounceRecord` and `ComplaintRecord` in Django Admin for failed deliveries. - Check `BounceRecord` in Django Admin for failed deliveries.
### Rate Limiting and Throttling ### Rate Limiting and Throttling
@ -298,16 +296,15 @@ System: Debugging and Error Handling
- Docs: https://docs.aws.amazon.com/ses/latest/dg/manage-sending-limits.html - Docs: https://docs.aws.amazon.com/ses/latest/dg/manage-sending-limits.html
## Changelog ## Changelog
For a detailed list of changes, improvements, and fixes across versions, see [CHANGELOG.md](CHANGELOG.md).
For a detailed list of changes, improvements, and fixes across versions, see CHANGELOG.md.
## Contributors ## Contributors
Developed by the ZeeksGeeks team. See CONTRIBUTORS.md for individual contributors and their roles. Developed by the ZeeksGeeks team. See [CONTRIBUTORS.md](CONTRIBUTORS.md) for individual contributors and their roles.
## License ## License
This project is licensed under the MIT License. See LICENSE for details. This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.
## PyPI Distribution ## PyPI Distribution
@ -315,4 +312,3 @@ This project is licensed under the MIT License. See LICENSE for details.
- Source: https://git-vault.zeeksgeeks.com/public/django_aws_ses - Source: https://git-vault.zeeksgeeks.com/public/django_aws_ses
- Issues: https://git-vault.zeeksgeeks.com/public/django_aws_ses/issues - Issues: https://git-vault.zeeksgeeks.com/public/django_aws_ses/issues
- PyPI: https://pypi.org/project/django-aws-ses/ - PyPI: https://pypi.org/project/django-aws-ses/
- Changelog: See CHANGELOG.md for version history.