Skip to main content

A model agnostic Django newsletter app integrating Mosaico.

Project description

Nuntius

Nuntius is a newsletter application for Django.

Nuntius integrates with your Django project. It is very agnostic about your subscribers and subscriber lists models.

It features Mosaico, a drag-and-drop email editor, for sending beautiful emails to your subscribers.

How it works

Nuntius is agnostic about your subscribers model. You can use your current use model, as long as it implements a few required methods.

To allow your end-users to choose recipients, it is your choice to implement one or more "segment" models. Segment models implement a required method get_subscribers_queryset.

You can then create campaigns in the Django admin panel, and send them to existing segments.

Celery is used to queue and send emails. Nuntius must have its own celery worker.

Installation

  1. Add "nuntius" to your INSTALLED_APPS setting like this:

        INSTALLED_APPS = [
            'django.contrib.admin',
            'django.contrib.auth',
            'django.contrib.contenttypes',
            'django.contrib.sessions',
            'django.contrib.messages',
            'django.contrib.staticfiles',
            ...
            'nuntius',
        ]
    
  2. Include Nuntius urlconf in your project urls.py like this:

        path('nuntius/', include('nuntius.urls')),
    
  3. Define your subscriber model so it works with Nuntius. You must inherit from nuntius.models.AbstractSubscriber and implement all the necessary methods. An easy way to do this is to use directly or to extend BaseSubscriber, but you can implement the methods of AbstractSubscriber the way you want.

    Here are the methods you must implement :

    • get_subscriber_status() must return one of AbstractSubscriber.STATUS_CHOICES. You can also simply define a subscriber_status attribute.

    • get_subscriber_email() must return a unique email address for the subscriber. You can also simply define an email attribute.

    • get_subscriber_data() must return the dictionnary of values which can be used as substitution in the emails. Default is {"email": self.get_subscriber_email()}.

  4. Set the two required settings in your settings.py

    NUNTIUS_SUBSCRIBER_MODEL = 'myapp.MySubscriberModel'
    NUNTIUS_CELERY_BROKER_URL = 'redis://'
    
  5. Launch Redis and celery in the background. In production, you should probably use systemd for this. The command for celery must be something like this (the app name, queue and node name options are required):

    export DJANGO_SETTINGS_MODULE=myapp.settings
    celery -A nuntius.celery worker -Q nuntius -n nuntius@%h
    

    Be careful if you have your own celery app in your project using the same broker. You should have two separate workers for your tasks and for Nuntius tasks, because Nuntius worker needs a special configuration to allow Nuntius to report correctly sendig state.

    Your worker for your project tasks must explicitely take tasks only from the default queue or any other queue you define. It must also have a different node name than the worker dedicated to nuntius.

    celery -A myapp.celery worker -Q celery
    
  6. Unless you are using a custom admin site, admin panels for Nuntius will be autodiscovered and added to you admin site. If you use a custom admin site, you need to register Nuntius models with something like:

    admin_site.register(nuntius.models.Campaign, nuntius.admin.CampaignAdmin)
    admin_site.register(nuntius.models.CampaignSentEvent, nuntius.admin.CampaignSentEventAdmin)
    

Advanced usage

List segments

If you want to have more control on your recipients, you can create a segment model.

One example of segment is a simple model which holds a Many-to-Many relation to subscribers.

Another example is a segment model which filters subscribers depending on the date of their last login :

from django.db import models
from django.db.models import fields
from datetime import datetime

from nuntius.models import BaseSegment


class LastLoginDateSegment(BaseSegment, models.Model):
     last_login_duration = fields.DurationField()

     def get_display_name(self):
         return f'Last login : {str(datetime.now() - self.last_login_duration)}'

     def get_subscribers_queryset(self):
        return MySubscriberClass.objects.filter(last_login__gt=datetime.now() - self.last_login_duration)

     def get_subscribers_count(self):
        return MySubscriberClass.objects.filter(last_login__gt=datetime.now() - self.last_login_duration, subscribed=True)
  • get_subscribers_queryset is allowed to return subscribers regardless of their subscriber_status, as get_subscriber_status will be called on each instance.
  • get_subscribers_count is only there for convenience in the admin panel, it does not have to be accurate. If you want to have it accurate, you should however take your subscribers status into account.

Then, add your segment model to Nuntius settings :

NUNTIUS_SEGMENT_MODEL = 'myapp.lastlogindatesegment'

Custom template

You can write your own Mosaico template to fit your needs. To make it available in the admin, list the public URL path of the template in NUNTIUS_MOSAICO_TEMPLATES. The template can be served by Django static files system, or any other way at your preference.

NUNTIUS_MOSAICO_TEMPLATES = [
    ("/static/mosaico_templates/versafix-2/template-versafix-2.html", "Custom template")
]

ESP and Webhooks

Maintaining your own SMTP server to send your newsletter is probably a bad idea if you have more than a few subscribers. You can use Anymail along with Nuntius in order to use an email service provider. Anymail supports a lot of ESP, like Amazon SES, Mailgun, Mailjet, Postmark, SendGrid, SendinBlue, or SparkPost.

Refer to the steps in Anymail 1-2-3 to install Anymail. If you want to configure Anymail just for Nuntius and keep the default email backend for other usage, you can use the setting NUNTIUS_EMAIL_BACKEND rather than the default EMAIL_BACKEND.

In addition, configuring Nuntius with Anymail will allow you to use ESP tracking features and to track status of your email once it is sent.

Webhooks

Configuring webhhoks allows Nuntius to track email status and to give you statistics on campaign, as well as updating subscriber status when they bounce.

  1. Configure email tracking as described in Anymail documentation.
  2. Implement the method set_subscriber_status(self, email, status) on your subscriber model manager.

Nuntius will automatically listen to Anymail signals and call this method approprietly.

License

Copyright is owned by Guillaume Royer and Arthur Cheysson.

You can use Nuntius under GPLv3 terms.

Project details


Release history Release notifications | RSS feed

Download files

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

Source Distribution

nuntius-1.0.0.tar.gz (2.6 MB view details)

Uploaded Source

Built Distribution

nuntius-1.0.0-py3-none-any.whl (2.7 MB view details)

Uploaded Python 3

File details

Details for the file nuntius-1.0.0.tar.gz.

File metadata

  • Download URL: nuntius-1.0.0.tar.gz
  • Upload date:
  • Size: 2.6 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.12.1 pkginfo/1.5.0.1 requests/2.21.0 setuptools/40.6.2 requests-toolbelt/0.9.1 tqdm/4.30.0 CPython/2.7.16

File hashes

Hashes for nuntius-1.0.0.tar.gz
Algorithm Hash digest
SHA256 52e0263140786bdfc97340a419bffcffeee377f51b8df7abe51a4130592669a6
MD5 588aa2581dd6953e6962af7d20d59f3f
BLAKE2b-256 c3dfd3144f00b9df546af1dabda85cd2f65577ce5b153d8d260ed19a629a27ed

See more details on using hashes here.

File details

Details for the file nuntius-1.0.0-py3-none-any.whl.

File metadata

  • Download URL: nuntius-1.0.0-py3-none-any.whl
  • Upload date:
  • Size: 2.7 MB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.12.1 pkginfo/1.5.0.1 requests/2.21.0 setuptools/40.6.2 requests-toolbelt/0.9.1 tqdm/4.30.0 CPython/2.7.16

File hashes

Hashes for nuntius-1.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 1900db71cebae0a770d2d67b74989b2d4398669c72e7911ee53a17eddb44089d
MD5 1d83f6abadde7c621eb4acfb5c2b77d6
BLAKE2b-256 6258a8153c86fcb23b1c9d51e98fac277a4cb3de4ed81405b9dc2f461769df52

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