Welcome to Pennyblack’s documentation!

Penyblack is a newsletter module based on the feincms.org CMS building toolkit. E-mails can either be sent as mass mails (e.g. monthly newsletter) or as part of a customised workflow (e.g. user clicks on a link and in response to that your application sends out an e-mail). Conditional data and variables can be filled in to a newsletter using the django template language. SPF (sender validation) and bounce management can be activated if desired. Key data like bounce rate, opening rate and link clicks is tracked and presented in the admin menu. Sending bulk e-mails is easy on memory. 20’000 and more addresses wont crash your server. From the outset we developed Pennyblack to easily integrate into existing web projects.

Contents:

Installation

This document describes the steps needed to set up pennyblack in your own project.

Since pennyblack is based on FeinCMS, you’ll need a FeinCMS installation first.

You can also install pennyblack using pip like so:

$ pip install pennyblack

Or you can grab your own copy of the pennyblack source from github:

$ git clone git://github.com/allink/pennyblack.git

Some features like spf detection need pyspf and pydns installations.

Make sure that the FeinCMS and pennyblack Apps are added to installed apps in the settings.py:

'feincms',
'feincms.module.medialibrary',
'pennyblack',

Add a newsletter url to the urls.py:

url(r'^newsletter/', include('pennyblack.urls'), name = 'pennyblack'),

Cronjob

To send emails and receive bounced emails these to management commands have to be executed:

./manage.py sendmail
./manage.py getmail

Configuration

To use pennyblacks newsletter model, you need to register html templates and content types like you do for the FeinCMS page module. Simple newsletter with only text content would look like this:

from pennyblack.models import Newsletter
from pennyblack.content.richtext import TextOnlyNewsletterContent

Newsletter.register_templates({
    'key': 'base',
    'title': 'Generic Newsletter',
    'path': 'pennyblack/base_newsletter.html',
    'regions': (
        ('main', 'Main Region'),
        ),
    })

Newsletter.create_content_type(TextOnlyNewsletterContent)

South Migrations

To use south migrations specify a south migration module in the settings:

SOUTH_MIGRATION_MODULES = {
    'pennyblack': 'project_name.migrations_pennyblack',
}

Content Types

Compared with FeinCMS content types, pennyblack content types can provide further functionality

Additional hooks

  • replace_links

    This method if it exists is called before the newsletter is sent. It should replace all links with a newly generated link to be able to track every link click:

    HREF_RE = re.compile(r'href\="((\{\{[^}]+\}\}|[^"><])+)"')

def replace_links(self, job):
    """
    Replaces all links and inserts pingback links
    """
    offset = 0
    for match in HREF_RE.finditer(self.text):
        link = match.group(1)
        if check_if_redirect_url(link):
            continue
        # don't replace links to proxy view
        if u'link_url' in link:
            continue
        replacelink = job.add_link(link)
        self.text = ''.join((self.text[:match.start(1)+offset], replacelink, self.text[match.end(1)+offset:]))
        offset += len(replacelink) - len(match.group(1))
  • prepare_to_send

    Is meant to add some additional style informations into the content. Because email clients often only accept inline style information.

    def prepare_to_send(self):
    """
    insert link_style into all a tags
    """
    self.text = re.sub(r"<a ","<a {% get_newsletterstyle request text_and_image_title %}", self.text)

Provided content types

Pennyblack comes with some content types bundled which sould be sufficient for most use cases.

Bouncedetection

Pennyblack comes with automatic bounce detection. Use the following explanation to get bounce detection up and running:

Configuration

the following in your settings file:

PENNYBLACK_BOUNCE_DETECTION_ENABLE = True

Mailman installation

To automatically detect bounces pennyblack uses a patched mailman installation which allows it to pass a email as text and receive a coma separated list of email addresses which have bounced. This is because mailman is published under gpl which only allows direct inclusion if only simple datatypes are exchanged.

  • Download a copy of mailman 2.x from http://www.list.org/download.html and unpack it into a directory which is on your python path.

  • Use the mailman_patch included in the gitrepository of pennyblack:

    cd Mailman
patch -p1 -i path_to/mailman_patch.patch

Sender configuration

Fill in imap credentials in for the sender in the admin and check Get bounce e-mails.

Cronjob

Set up a cronjob to execute ./manage.py getmail regularly.

Where did all the emails go?

Pennyblack moves every email which is recognized as a bounce email into INBOX.bounced. This folder can be renamed by altering the settings.

Settings

General Settings

pennyblack.default_settings.TINYMCE_CONFIG_URL

Newsletter

pennyblack.default_settings.NEWSLETTER_TYPE

Defines the available newsletter types. Normally you don’t have to change these.

pennyblack.default_settings.NEWSLETTER_TYPE_MASSMAIL

A tuple with all NEWSLETTER_TYPE id’s which are considered a massmail newsletter.

Massmail are newsletters which are sent to many receivers at the same time.

pennyblack.default_settings.NEWSLETTER_TYPE_WORKFLOW

A tuple with all NEWSLETTER_TYPE id’s wich are considered a workflow newsletter.

Workflow newsletters are emails wich are sent to each receiver indivitually, for example a registration complete email wich is sent right after a user registers.

pennyblack.default_settings.NEWSLETTER_CONTENT_WIDTH

The content with of a newsletter, has to match the with in the template.

pennyblack.default_settings.TEXT_AND_IMAGE_CONTENT_POSITIONS

A list of position choices for the TextWithImageNewsletterContent.

pennyblack.default_settings.TEXT_AND_IMAGE_CONTENT_IMAGE_WIDTH_SIDE
pennyblack.default_settings.JPEG_QUALITY

The quality in percent which is used to compress jpeg images.

Job

pennyblack.default_settings.JOB_STATUS
pennyblack.default_settings.JOB_STATUS_CAN_SEND
pennyblack.default_settings.JOB_STATUS_PENDING
pennyblack.default_settings.JOB_STATUS_CAN_EDIT

Bounce detection

pennyblack.default_settings.BOUNCE_DETECTION_ENABLE
pennyblack.default_settings.BOUNCE_DETECTION_DAYS_TO_LOOK_BACK
pennyblack.default_settings.BOUNCE_DETECTION_BOUNCE_EMAIL_FOLDER

Integration

This section describes how to integrate pennyblack into your project.

Template

Since pennyblack is heavily based on the feincms base model, you have to register at least one template to use it. There is a example template called base_newsletter.html in the templates folder which you could register like shown in the example project.

from pennyblack.models import Newsletter

Newsletter.register_templates({
    'key': 'base',
    'title': 'Generic Newsletter',
    'path': 'base_newsletter.html',
    'regions': (
        ('main', 'Main Region'),
        ),
    })

Context

By default the template context in emails is as follows:

person: person object group_object: corresponding group (only if available) mail: the mail object base_url: base url

Models

The pennyblack core models

Releases

Pennyblack 0.3.0 release notes

Changes 0.3.2

  • Don’t save pickled views to database because of problems when migrating or upgrading.

Changes 0.3.1

  • Fix tracking of image links in Text and image content
  • Some improvements in the default templates

Changes 0.3.0

  • Added a patch to patch mailman 2.x and changed the import to meet this new setup.
  • Send confirmation view now shows a valid email. This should help to not send newsletters with wrong variables set.
  • Some more information in the statistics view.
  • Documentation overhaul.

Upgrade

  • If you use bounce detection you have to change the name of the BouncerApi file from BouncerAPI_new.py to BouncerAPI.py

Indices and tables