Installation

  1. Make sure all requirements are properly setup.

  2. Get it from the Cheese Shop:

    pip install django-newsletter
    

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

    pip install -e git://github.com/dokterbob/django-newsletter.git#egg=django-newsletter
    

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

  3. Add newsletter to INSTALLED_APPS in settings.py and make sure that your favourite rich text widget (optional), some Django contrib dependencies, sorl-thumbnail and django-extensions (the latter is used for the submission jobs) are there as well:

    INSTALLED_APPS = (
        'django.contrib.contenttypes',
        'django.contrib.sessions',
        'django.contrib.auth',
        'django.contrib.sites',
        ...
        # Imperavi (or tinymce) rich text editor is optional
        # 'imperavi',
        'django_extensions',
        'sorl.thumbnail',
        ...
        'newsletter',
        ...
    )
    
  4. Disable email confirmation for subscribe, unsubscribe and update actions for subscriptions.

    By default subscribe, unsubscribe and update requests made by a user who is not logged in need to be confirmed by clicking on an activation link in an email. If you want all requested actions to be performed without email confirmation, add following line to settings.py:

    NEWSLETTER_CONFIRM_EMAIL = False
    

    For more granular control the NEWSLETTER_CONFIRM_EMAIL setting can be overridden for each of subscribe, unsubscribe and update actions, by adding NEWSLETTER_CONFIRM_EMAIL_SUBSCRIBE and/or NEWSLETTER_CONFIRM_EMAIL_UNSUBSCRIBE and/or NEWSLETTER_CONFIRM_EMAIL_UPDATE set to True or False.

  5. Install and configure your preferred rich text widget (optional).

    Known to work are django-imperavi as well as for django-tinymce. Be sure to follow installation instructions for respective widgets. After installation, the widgets can be selected as follows:

    # Using django-imperavi
    NEWSLETTER_RICHTEXT_WIDGET = "imperavi.widget.ImperaviWidget"
    
    # Using django-tinymce
    NEWSLETTER_RICHTEXT_WIDGET = "tinymce.widgets.TinyMCE"
    

    If not set, django-newsletter will fall back to Django’s default TextField widget.

  6. Configure delay and batch size (optional).

    The delay between each email, batches en batch size can be specified with e.g.:

    # Amount of seconds to wait between each email. Here 100ms is used.
    ``NEWSLETTER_EMAIL_DELAY = 0.1``
    
    # Amount of seconds to wait between each batch. Here one minute is used.
    ``NEWSLETTER_BATCH_DELAY = 60``
    
    # Number of emails in one batch
    ``NEWSLETTER_BATCH_SIZE = 100``
    

    For both delays, sub-second delays can also be used. If the delays are not set, it will default to not sleeping.

  7. Import subscription, unsubscription and archive URL’s somewhere in your urls.py:

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

  9. Create the required data structure:

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

  11. (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.

  12. Add jobs for sending out mail queues to crontab:

    @hourly /path/to/my/project/manage.py runjobs hourly
    @daily /path/to/my/project/manage.py runjobs daily
    @weekly /path/to/my/project/manage.py runjobs weekly
    @monthly /path/to/my/project/manage.py runjobs monthly
    

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