Skip to main content

A notifications library for Djangonauts that support email, sms and push.

Project description

Django Magic Notifier

Travis CI Coverage PyPI Version Documentation Python Versions Django Versions

Published on Django Packages


Why Choose Django Magic Notifier?

Managing notifications in Django applications can often be a complex and cumbersome task. Django Magic Notifier (DMN) simplifies this by consolidating all your notification needs into a single, powerful API: notify(). Whether you need to send emails, SMS, WhatsApp messages, Telegram notifications, or push notifications, DMN handles it all seamlessly.


Features

  • Unified Notification API: One function notify() to handle all notification types.
  • Multi-Channel Support: Email, SMS, WhatsApp, Telegram, and push notifications.
  • Gateway Flexibility: Configure multiple gateways per channel with ease.
  • Template-Based Messages: Use templates for consistent and professional notifications.
  • File Attachments: Include files in your notifications.
  • Asynchronous Notifications: Threaded support for background processing.
  • Extensibility: Add custom gateways or notification types.
  • MJML Support: Use modern, responsive email designs.

Installation

Install Django Magic Notifier using pip:

pip install --upgrade django-magic-notifier

Configuration

Add the NOTIFIER configuration to your Django settings.py file. Below is an example of a complete configuration:

NOTIFIER = {
    "EMAIL": {
        "default": {
            "HOST": "localhost",
            "PORT": 587,
            "USE_TLS": True,
            "USE_SSL": False,
            "USER": "root@localhost",
            "FROM": "Root <root@localhost>",
            "PASSWORD": "password",
            "CLIENT": "magic_notifier.email_clients.django_email.DjangoEmailClient",
        },
        "ses": {
            "CLIENT": "magic_notifier.email_clients.amazon_ses.AmazonSesClient",
            "AWS_ACCESS_KEY": "****************",
            "AWS_SECRET_KEY": "****************************************",
            "AWS_REGION_NAME": "eu-north-1",
            "AWS_REGION_ENDPOINT": "https://email.eu-north-1.amazonaws.com",
            "FROM": "Service <account@service.se>",
        },
        "DEFAULT_GATEWAY": "ses",  # use amazon ses as the default gateway
        "FALLBACKS": ["default"]  # if the default gateway fails, fallback to these gateways
    },
    "WHATSAPP": {
        "DEFAULT_GATEWAY": "waha",
        "GATEWAYS": {
            "waha": {
                "BASE_URL": "http://localhost:3000"
            }
        }
    },
    "TELEGRAM": {
        "DEFAULT_GATEWAY": "default",
        "GATEWAYS": {
            "default": {
                "API_ID": "xxxxxx",
                "API_HASH": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
            }
        }
    },
    "SMS": {
        "DEFAULT_GATEWAY": "TWILIO",
        "GATEWAYS": {
            "TWILIO": {
                "CLIENT": "magic_notifier.sms_clients.twilio_client.TwilioClient",
                "ACCOUNT": "account_sid",
                "TOKEN": "auth_token",
                "FROM_NUMBER": "+1234567890"
            }
        }
    },
    "USER_FROM_WS_TOKEN_FUNCTION": "magic_notifier.utils.get_user_from_ws_token",
    "GET_USER_NUMBER": "magic_notifier.utils.get_user_number",
    "THREADED": True
}

Key Settings

  • EMAIL: Configure your email gateway, including host, port, and credentials.
  • WHATSAPP: Define the WhatsApp gateway with its base URL.
  • TELEGRAM: Configure Telegram with API credentials.
  • SMS: Specify SMS gateways such as Twilio, Nexa, or others.
  • THREADED: Enable background processing for notifications.

Usage

Sending Notifications

The notify() function is your gateway to all notification types.

Basic Email Notification

from magic_notifier.notifier import notify

user = User.objects.get(email="testuser@localhost")
subject = "Welcome!"
notify(["email"], subject, [user], final_message="Welcome to our platform!")

SMS Notification with Template

notify(["sms"], "Account Alert", [user], template="account_alert")

Multi-Channel Notification

notify(["email", "sms"], "System Update", [user], final_message="The system will be down for maintenance.")

WhatsApp Notification

notify(["whatsapp"], "Welcome", [user], final_message="Hello! This is a WhatsApp test message.")

Telegram Notification

notify(["telegram"], "Welcome", [user], final_message="Hello! This is a Telegram test message.")

Passing Context to Templates

You can pass additional context to your templates via the context argument, note that the user object is automatically passed:

context = {
    "discount": 20
}
notify(["email"], "Special Offer", [user], template="special_offer", context=context)

In the template:

{% block content %}
<p>Hi {{ user.first_name }},</p>
<p>We are excited to offer you a {{ discount }}% discount on your next purchase!</p>
{% endblock %}

Overriding Gateways

You can override default gateways directly when sending notifications:

Override Email Gateway

notify(["email"], "Custom Email Gateway", [user], final_message="This uses a custom email gateway.", email_gateway="custom_gateway")

Override SMS Gateway

notify(["sms"], "Custom SMS Gateway", [user], final_message="This uses a custom SMS gateway.", sms_gateway="custom_sms_gateway")

Override WhatsApp Gateway

notify(["whatsapp"], "Custom WhatsApp Gateway", [user], final_message="This uses a custom WhatsApp gateway.", whatsapp_gateway="custom_whatsapp_gateway")

Override Telegram Gateway

notify(["telegram"], "Custom Telegram Gateway", [user], final_message="This uses a custom Telegram gateway.", telegram_gateway="custom_telegram_gateway")

Template Creation and Resolution

When using templates, Django Magic Notifier looks for specific files depending on the notification channels. The template value designates a folder, not a file. Files are checked in the following order for each channel:

  • Email: email.mjml -> email.html -> email.txt
  • SMS: sms.txt
  • WhatsApp: whatsapp.txt -> sms.txt
  • Telegram: telegram.txt -> sms.txt

If a file is not found, the next file in the sequence is checked. If no files are found, an error is raised.

Example

Suppose notify() is called as follows:

notify(["telegram"], "Welcome", [user], template="welcome")

The following files will be checked in order:

  1. notifier/welcome/telegram.txt
  2. notifier/welcome/sms.txt

Ensure that at least one of these files exists in your templates directory.


Advanced Features

Sending Files

Attach files to your notifications:

files = ["/path/to/file.pdf"]
notify(["email"], "Invoice", [user], final_message="Your invoice is attached.", files=files)

Sending to Specific Receiver Groups

The notify() function supports predefined values for the receivers argument to target specific user groups:

Sending to Admin Users

notify(["email"], "Admin Alert", "admins", final_message="This is a message for all admin users.")

Sending to Staff Users

notify(["email"], "Staff Notification", "staff", final_message="This message is for all staff members.")

Sending to All Users

notify(["email"], "Global Announcement", "all", final_message="This is a message for all users.")

Sending to Non-Staff Users

notify(["email"], "Non-Staff Update", "all-staff", final_message="This message is for users who are not staff.")

Sending to Non-Admin Users

notify(["email"], "User Alert", "all-admins", final_message="This is a message for all users except admins.")

Asynchronous Processing

Enable threaded notifications for better performance:

notify(["sms"], "Alert", [user], final_message="This is a test.", threaded=True)

Testing

DMN includes comprehensive test cases for all features. To run tests:

python manage.py test

Roadmap

  • Extend support for additional messaging platforms.

Contributing

We welcome contributions! To get started, fork the repository, make your changes, and submit a pull request. Refer to our contributing guidelines for more details.


License

This project is licensed under the MIT License. See the LICENSE file for details.


Support

File an issue on GitHub.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django_magic_notifier-0.4.0.tar.gz (25.4 kB view details)

Uploaded Source

Built Distribution

django_magic_notifier-0.4.0-py2.py3-none-any.whl (35.5 kB view details)

Uploaded Python 2Python 3

File details

Details for the file django_magic_notifier-0.4.0.tar.gz.

File metadata

  • Download URL: django_magic_notifier-0.4.0.tar.gz
  • Upload date:
  • Size: 25.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.8.20

File hashes

Hashes for django_magic_notifier-0.4.0.tar.gz
Algorithm Hash digest
SHA256 458f9f2a1dd4740b7162b1b25e52c9a75a72281a2c9e614629767cac744ded28
MD5 1c749a02095f751c0ad6364c977f50e3
BLAKE2b-256 d504828ccfd0fe4ef95c717ce751f5707edc75a44505f4aaee4a81e3dfe708dd

See more details on using hashes here.

File details

Details for the file django_magic_notifier-0.4.0-py2.py3-none-any.whl.

File metadata

File hashes

Hashes for django_magic_notifier-0.4.0-py2.py3-none-any.whl
Algorithm Hash digest
SHA256 b47aa2cea10336b4d4ceb2ddc0c70a67fd74e9f6295aae3a2f8b5c5285c390ef
MD5 6e23d677a8bc080e6c49da53f4a2053d
BLAKE2b-256 708090b52a2f6e97b0ce35908acbfda5fa9255ea25079c394470451a5c8fec92

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page