1. Install the package from PyPI:

    pip install django-newsletter

    Or get the latest & greatest from Github and link it to your application tree:

    pip install -e git://

    (In either case it is recommended that you use VirtualEnv in order to keep your Python environment somewhat clean.)

  2. Add newsletter and the Django contrib dependencies noted below to INSTALLED_APPS in your settings file.

    You will need one of the supported thumbnail applications ( sorl-thumbnail or easy-thumbnails).

    You may also add an optional rich text widget ( Django Imperavi or Django TinyMCE) and

        # Required Contrib Apps
        # At least *one* of these thumbnail applications
        # Optionally, one of Imperavi or TinyMCE WYSIWYG editors
  3. Specify your thumbnail application in your settings file:

    # Using sorl-thumbnail
    NEWSLETTER_THUMBNAIL = 'sorl-thumbnail'
    # Using easy-thumbnails
    NEWSLETTER_THUMBNAIL = 'easy-thumbnails'
  4. Configure any of the optional Settings.

  5. Import subscription, unsubscription and archive URL’s somewhere in your

    urlpatterns = [
        path('newsletter/', include('newsletter.urls')),
  6. Enable Django’s staticfiles app so the admin icons, CSS and JavaScript will be available where we expect it.

  7. Create the required data structure:

    ./ migrate
  8. Change the default contact email listed in templates/newsletter/subscription_subscribe.html and templates/newsletter/subscription_update.html.

  9. (Optionally) Create message template overrides for specific newsletters in templates/newsletter/message/<newsletter_slug>/<message_type>[_subject].<html|txt> where <message_type> can be one from subscribe, unsubscribe, message or update.

  10. You may now navigate to the Django admin where the Newsletter module should be available for you to play with.

    In order to test if submissions work, make sure you create a newsletter, a subscription, a message and finally a submission.

    After creating the submission, you must schedule it by clicking the ‘submit’ button in the top right of the page where you edit it.

  11. Now you may perform a test submission with the submit_newsletter management command (-v 2 is for extra verbosity):

    ./ submit_newsletter -v 2
  12. Add the submit_newsletter management command to crontab.

    For example (for sending every 15 minutes):

    */15  *  *   *   *     <path_to_virtualenv>/bin/python <project_root>/ submit_newsletter 1>/dev/null 2>&1

To send mail, django-newsletter uses Django-provided email utilities, so ensure that email settings are properly configured for your project.