django-aida-notifications 1.0.0

A comprehensive Django notification extension with email (via Anymail) and SMS (via Twilio) support

Django AIDA Notifications

A comprehensive Django notification extension that provides email and SMS notification capabilities with template management, delivery tracking, and support for multiple providers.

Features

• Multi-channel Support: Send notifications via Email and SMS
• Template Management: Create and manage reusable notification templates with Django template syntax
• Provider Abstraction: Easy switching between email providers (via Django Anymail) and SMS providers (Twilio)
• Delivery Tracking: Complete logging of all sent notifications with status tracking
• User Preferences: Allow users to control their notification preferences
• Batch Sending: Send notifications to multiple recipients efficiently
• Admin Interface: Full Django admin integration for managing templates and viewing logs
• Test Mode: Safe testing without sending actual notifications
• Retry Logic: Automatic retry for failed notifications
• Django 5.1 Compatible: Supports Django 3.2 through 5.1

Installation

From PyPI (Recommended)

pip install django-aida-notifications

From GitHub

pip install git+https://github.com/hmesfin/aida-notifications.git

From Source

git clone https://github.com/hmesfin/aida-notifications.git
cd aida-notifications
pip install -e .

Quick Start

1. Add to Django Settings

# settings.py

INSTALLED_APPS = [
    ...
    'aida_notifications',
    'anymail',  # Required for email support
    ...
]

# Anymail Configuration
ANYMAIL = {
    "SENDGRID_API_KEY": "your-sendgrid-api-key",
    # Or use another provider like Mailgun, Postmark, etc.
}
EMAIL_BACKEND = "anymail.backends.sendgrid.EmailBackend"

# AIDA Notifications Configuration
AIDA_NOTIFICATIONS = {
    'DEFAULT_FROM_EMAIL': '[e-mail]',
    'DEFAULT_FROM_NAME': 'Your App Name',
    'TWILIO_ACCOUNT_SID': 'your-twilio-account-sid',
    'TWILIO_AUTH_TOKEN': 'your-twilio-auth-token',
    'TWILIO_FROM_NUMBER': '[phone]',
    'LOG_NOTIFICATIONS': True,
    'TEST_MODE': False,  # Set to True for testing
}

2. Run Migrations

python manage.py migrate aida_notifications

3. Create Sample Templates

python manage.py create_sample_templates

4. Send Your First Notification

from aida_notifications.service import notification_service

# Send a simple email
notification_service.send_email(
    recipient='[e-mail]',
    subject='Welcome!',
    body='Welcome to our platform!',
    html_body='<h1>Welcome to our platform!</h1>'
)

# Send using a template
notification_service.send_email(
    recipient=user,  # Can be a User object
    template_name='welcome_email',
    context={
        'user': user,
        'site_name': 'My App'
    }
)

# Send an SMS
notification_service.send_sms(
    recipient='[phone]',
    body='Your verification code is 123456'
)

Configuration Options

Email Providers (via Django Anymail)

AIDA Notifications uses Django Anymail for email delivery, supporting multiple providers:

• SendGrid
• Mailgun
• Postmark
• Amazon SES
• SparkPost
• Mandrill
• Sendinblue
• And more...

Example configuration for different providers:

# SendGrid
ANYMAIL = {
    "SENDGRID_API_KEY": "your-api-key",
}
EMAIL_BACKEND = "anymail.backends.sendgrid.EmailBackend"

# Mailgun
ANYMAIL = {
    "MAILGUN_API_KEY": "your-api-key",
    "MAILGUN_SENDER_DOMAIN": "mg.example.com",
}
EMAIL_BACKEND = "anymail.backends.mailgun.EmailBackend"

# Amazon SES
ANYMAIL = {
    "AMAZON_SES_CLIENT_PARAMS": {
        "aws_access_key_id": "your-access-key",
        "aws_secret_access_key": "your-secret-key",
        "region_name": "us-east-1",
    },
}
EMAIL_BACKEND = "anymail.backends.amazon_ses.EmailBackend"

SMS Configuration (Twilio)

AIDA_NOTIFICATIONS = {
    'TWILIO_ACCOUNT_SID': 'your-account-sid',
    'TWILIO_AUTH_TOKEN': 'your-auth-token',
    'TWILIO_FROM_NUMBER': '[phone]',
    # Or use Messaging Service SID instead
    'TWILIO_MESSAGING_SERVICE_SID': 'your-messaging-service-sid',
}

Advanced Settings

AIDA_NOTIFICATIONS = {
    # Retry Configuration
    'RETRY_FAILED_NOTIFICATIONS': True,
    'MAX_RETRY_ATTEMPTS': 3,
    'RETRY_DELAY_SECONDS': 300,
    
    # Rate Limiting
    'ENABLE_RATE_LIMITING': True,
    'RATE_LIMIT_PER_HOUR': 100,
    
    # Batch Processing
    'BATCH_SIZE': 100,
    'USE_CELERY': True,  # For async processing
    
    # Testing
    'TEST_MODE': False,
    'TEST_MODE_RECIPIENTS': {
        'email': ['[e-mail]'],
        'sms': ['[phone]']
    }
}

Template Management

Creating Templates

Templates can be created via Django admin or programmatically:

from aida_notifications.models import NotificationTemplate

template = NotificationTemplate.objects.create(
    name='order_confirmation',
    channel='email',
    subject='Order #{{ order.id }} Confirmed',
    body_template='''
    Hi {{ user.first_name }},
    
    Your order #{{ order.id }} has been confirmed.
    Total: ${{ order.total }}
    
    Thank you for your purchase!
    ''',
    html_template='''
    <h2>Order Confirmation</h2>
    <p>Hi {{ user.first_name }},</p>
    <p>Your order #{{ order.id }} has been confirmed.</p>
    <p><strong>Total: ${{ order.total }}</strong></p>
    <p>Thank you for your purchase!</p>
    ''',
    variables={
        'user': 'User object',
        'order': 'Order object'
    }
)

Using Templates

from aida_notifications.service import notification_service

# Send to a single user
notification_service.send_notification(
    recipient=user,
    template_name='order_confirmation',
    channel='email',
    context={
        'user': user,
        'order': order
    }
)

# Send to multiple recipients
notification_service.send_batch(
    recipients=[user1, user2, user3],
    template_name='newsletter',
    channel='email',
    context={
        'newsletter_date': 'January 2024'
    }
)

User Preferences

Allow users to manage their notification preferences:

from aida_notifications.models import NotificationPreference

# Create or update preferences
pref, created = NotificationPreference.objects.get_or_create(
    user=user,
    defaults={
        'email_enabled': True,
        'sms_enabled': True,
        'email_address': user.email,
        'phone_number': '[phone]'
    }
)

# Disable email notifications
pref.email_enabled = False
pref.save()

Management Commands

Test Notifications

# Test email
python manage.py test_notification email [e-mail] \
    --subject "Test Email" \
    --body "This is a test email"

# Test SMS
python manage.py test_notification sms [phone] \
    --body "This is a test SMS"

# Test with template
python manage.py test_notification email [e-mail] \
    --template welcome_email \
    --context '{"user": {"first_name": "John"}}'

Create Sample Templates

python manage.py create_sample_templates

Admin Interface

The extension provides a comprehensive Django admin interface for:

• Templates: Create, edit, and preview notification templates
• Logs: View all sent notifications with filtering and search
• Preferences: Manage user notification preferences
• Batches: Monitor batch notification jobs

Access the admin at /admin/aida_notifications/

API Reference

NotificationService

from aida_notifications.service import notification_service

# Send email
notification_service.send_email(
    recipient='[e-mail]',  # or User object
    subject='Subject',
    body='Plain text body',
    html_body='<p>HTML body</p>',
    template_name='template_name',  # Optional
    context={},  # Template context
    reply_to='[e-mail]',
    attachments=[
        {
            'filename': 'document.pdf',
            'content': file_content,
            'mimetype': 'application/pdf'
        }
    ]
)

# Send SMS
notification_service.send_sms(
    recipient='[phone]',  # or User object
    body='SMS message',
    template_name='template_name',  # Optional
    context={},  # Template context
    media_url='https://example.com/image.jpg'  # MMS
)

# Send batch
batch = notification_service.send_batch(
    recipients=[user1, user2, user3],
    template_name='newsletter',
    channel='email',
    context={'month': 'January'},
    batch_name='January Newsletter'
)

# Retry failed notifications
retried_count = notification_service.retry_failed_notifications(hours=24)

Testing

Running Tests

# Run all tests
python manage.py test aida_notifications

# Run with coverage
pytest --cov=aida_notifications tests/

Test Mode

Enable test mode to prevent actual notifications from being sent:

AIDA_NOTIFICATIONS = {
    'TEST_MODE': True,
    'TEST_MODE_RECIPIENTS': {
        'email': ['[e-mail]'],
        'sms': ['[phone]']
    }
}

Celery Integration

For asynchronous notification sending, integrate with Celery:

# tasks.py
from celery import shared_task
from aida_notifications.service import notification_service

@shared_task
def send_notification_async(recipient, template_name, channel, context):
    return notification_service.send_notification(
        recipient=recipient,
        template_name=template_name,
        channel=channel,
        context=context
    )

Error Handling

from aida_notifications.service import notification_service
from aida_notifications.models import NotificationLog

try:
    log = notification_service.send_email(
        recipient='[e-mail]',
        subject='Test',
        body='Test message'
    )
    
    if log.status == NotificationLog.STATUS_SENT:
        print(f"Sent successfully: {log.provider_message_id}")
    else:
        print(f"Failed: {log.error_message}")
        
except Exception as e:
    print(f"Error: {e}")

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License.

Support

For issues and questions, please use the GitHub issue tracker.

Changelog

Version 1.0.0

• Initial release
• Email support via Django Anymail
• SMS support via Twilio
• Template management
• User preferences
• Batch sending
• Django 5.1 compatibility