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

added changelog to readme

This commit is contained in:
Raymond Jessop 2025-04-22 23:13:39 -05:00
parent 7b1e3bd5e7
commit 922392a332
3 changed files with 59 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
CHANGELOG.md
View File

@ -2,23 +2,37 @@
All notable changes to `django_aws_ses` will be documented in this file. All notable changes to `django_aws_ses` will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.
## 0.1.2 - 2025-04-22
## [0.1.2] - 2025-04-22
### Added ### Added
- `CHANGELOG.md` to document version history. - `CHANGELOG.md` to document version history.
- Clickable table of contents in `README.md` for improved navigation.
- Expanded `README.md` sections for AWS SES configuration and usage, with detailed instructions and AWS documentation links.
- Note in `README.md` Usage section clarifying examples are in a Python console.
### Changed
- Updated `README.md` to use `https://yourdomain.com` consistently for example URLs.
- Improved `README.md` formatting for better rendering on PyPI.
## 0.1.1 - 2025-04-22
## [0.1.1] - 2025-04-22
### Added ### Added
- Comprehensive installation steps in `README.md`, covering PyPI, and dependency options (`dev`, `dkim`).
- Comprehensive installation steps in `README.md`, covering PyPI and dependency options (`dev`, `dkim`).
- `CONTRIBUTORS.md` to acknowledge ZeeksGeeks team members and their roles. - `CONTRIBUTORS.md` to acknowledge ZeeksGeeks team members and their roles.
### Changed ### Changed
- Updated `README.md` formatting for better rendering on PyPI.
- Incremented version to `0.1.1` to reflect documentation improvements. - Incremented version to `0.1.1` to reflect documentation improvements.
## [0.1.0] - 2025-04-15 ## 0.1.0 - 2025-04-15
### Added ### Added
- Initial release of `django_aws_ses`. - Initial release of `django_aws_ses`.
- Custom Django email backend for Amazon SES. - Custom Django email backend for Amazon SES.
- Bounce and complaint handling via SNS notifications. - Bounce and complaint handling via SNS notifications.
@ -29,9 +43,6 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
- Comprehensive test suite covering email sending, bounce/complaint handling, and unsubscribe functionality. - Comprehensive test suite covering email sending, bounce/complaint handling, and unsubscribe functionality.
### Notes ### Notes
- Initial release tested with Django 3.2+ and Python 3.6+.
- Successfully deployed to TestPyPI for validation.
[0.1.0.2]: https://git-vault.zeeksgeeks.com/ZeeksGeeks/django_aws_ses/compare/0.1.0.1...0.1.0.2 - Initial release tested with Django 3.2+ and Python 3.6+.
[0.1.0.1]: https://git-vault.zeeksgeeks.com/ZeeksGeeks/django_aws_ses/compare/0.1.0...0.1.0.1 - Successfully deployed to TestPyPI for validation.
[0.1.0]: https://git-vault.zeeksgeeks.com/ZeeksGeeks/django_aws_ses/releases/tag/0.1.0

66
README.md
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-statistics52) - 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 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 unsubscribe functionality. - Secure unsubscribe functionality with non-expiring links and GET/POST protection.
- Django Admin dashboard for SES statistics. - Django Admin dashboard for SES statistics (superusers only).
- (Optional) Supports DKIM signing, requires `dkimpy`. - Optional DKIM signing support (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`): Run migrations to create the `django_aws_ses` models (e.g., `AwsSesSettings`, `BounceRecord`, `ComplaintRecord`, `SendRecord`, `AwsSesUserAddon`):
```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` model. - Records are stored in the `BounceRecord` and `ComplaintRecord` models.
- 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,21 +270,23 @@ 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 Phelps ### Viewing SES Statistics
- 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` and SES API data for metrics. - Uses `BounceRecord`, `ComplaintRecord`, and `SendRecord` models 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` in Django Admin for failed deliveries. - Check `BounceRecord` and `ComplaintRecord` in Django Admin for failed deliveries.
### Rate Limiting and Throttling ### Rate Limiting and Throttling
@ -296,7 +298,8 @@ unsubscribe_url = addon.unsubscribe_url_generator()
- 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
@ -311,4 +314,5 @@ This project is licensed under the MIT License. See LICENSE for details.
- Install: `pip install django-aws-ses` - Install: `pip install django-aws-ses`
- 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.

4
setup.py
View File

@ -5,13 +5,13 @@ with open("README.md", "r", encoding="utf-8") as fh:
setup( setup(
name="django_aws_ses", name="django_aws_ses",
version="0.1.0", version="0.1.2",
author="ZeeksGeeks", author="ZeeksGeeks",
author_email="contact@zeeksgeeks.com", author_email="contact@zeeksgeeks.com",
description="A Django email backend for Amazon SES with bounce and complaint handling", description="A Django email backend for Amazon SES with bounce and complaint handling",
long_description=long_description, long_description=long_description,
long_description_content_type="text/markdown", long_description_content_type="text/markdown",
url="https://git-vault.zeeksgeeks.com/public/django_aws_ses", # Replace with your repo or website url="https://git-vault.zeeksgeeks.com/public/django_aws_ses",
packages=find_packages(), packages=find_packages(),
include_package_data=True, include_package_data=True,
install_requires=[ install_requires=[