django-ilmoitin 0.5.0

Django app for sending notifications.

django-ilmoitin

A templated Django messaging library

Installation

1. pip install django-ilmoitin

2. Add django_ilmoitin to INSTALLED_APPS.

3. Run migrations

   python manage.py migrate ilmoitin
   

Usage

1. django-ilmoitin uses django-mailer to send emails, so you need to configure the MAILER_EMAIL_BACKEND setting to let django-mailer know, how to actually send the mail:

   MAILER_EMAIL_BACKEND = "your.actual.EmailBackend"
   

2. Define default from address in settings

   DEFAULT_FROM_EMAIL = "Ilmoitin <[e-mail]>"
   

   In case you need translated from addresses, those can be defined like

   ILMOITIN_TRANSLATED_FROM_EMAIL: {
      "fi": "Yrjö <[e-mail]>",
      "en": "George <[e-mail]>",
   }
   

   The value from DEFAULT_FROM_EMAIL will be used for languages not defined in that dict.

3. Create a notifications.py file in django app and register your notification types:

   from django_ilmoitin.registry import notifications
   
   notifications.register("event_created", "Event created")
   notifications.register("event_deleted", "Event deleted")
   

4. Create a dummy_context.py file in django app and add dummy context data. Either use the codes of notifications that you registered in the previous step, or use the const COMMON_CONTEXT to make some variables available for all templates:

   from django_ilmoitin.dummy_context import COMMON_CONTEXT, dummy_context
   
   from .models import MyModel
   
   my_object = MyModel(foo="bar")
   
   dummy_context.update({
       COMMON_CONTEXT: {"my_object": my_object},
       "event_created": {
           "foo": "bar"
       },
       "event_deleted": {
           "fizz": "buzz"
       }
   })
   

5. Import notifications and dummy context in your apps.py:

   from django.apps import AppConfig
   
   
   class ExampleConfig(AppConfig):
       name = "example"
   
       def ready(self):
           import example.notifications
           import example.dummy_context
   

6. Go to django admin and add notification templates to your notifications

7. Send notifications. List of attachment files can be passed as last optional argument:

   from django_ilmoitin.utils import send_notification
   
   context = {
       "foo": "bar",
   }
   attachment = "test.txt", "foo bar", "text/plain"
   
   send_notification("[e-mail]", "event_created", context, [attachment])
   

8. By default, notifications will be sent immediately, if you only want to add notification to the message queue and send it later, configure ILMOITIN_QUEUE_NOTIFICATIONS:

   ILMOITIN_QUEUE_NOTIFICATIONS = True
   

Using the GraphQL API

The package provides an optional GraphQL API that requires a working graphene API to work, and it needs additional dependencies.

1. To install them, run: pip install django-ilmoitin[graphql_api]

2. Add the Query to the entrypoint where you build your schema:

# my_app/schema.py
import django_ilmoitin.api.schema as django_ilmoitin_schema

class Query(
    # other extended classes
    django_ilmoitin_schema.Query,
    graphene.ObjectType,
):
    pass

Code format

This project uses black for Python code formatting. We follow the basic config, without any modifications. Basic black commands:

• To let black do its magic: black .
• To see which files black would change: black --check .

Troubleshooting guide

1. Cannot receive email even though it was sent successfully

• Some strict spam filter might mark email as spam if its Message-ID header has suspicious domain name (e.g 158431519447.10.15335486611387428798@qa-staging-i09m9b-staging-77bd999444-p2497)

• This is because Python tries to generate messsage id base on the FQDN of the local machine before sending email . Fortunately most of Email Sending services (Mailgun, MailChimp, Sendgrid,..) have a way to generate a reliable message-id that will likely pass spam filter, so we better let them do it.

• If you are using django-anymail as the email backend, there is an easy way to remove the auto-generated Message ID using pre_send signal

• Example:

    from anymail.signals import pre_send
    @receiver(pre_send)
    def remove_message_id(sender, message, **kwargs):
        message.extra_headers.pop("Message-ID", None)

Note that it only works if you are using django-anymail as your email backend