boletin 0.5.1

Newsletter generation and sending application for Django

.. contents::

================================
Boletin, a Django newsletter app
================================

Boletin is a generic newsletter application for Django projects, which allows
for automatically generating and sending newsletters, with optional human
reviewing process if so desired.

Boletin means "bulletin" or "newsletter" in Spanish.


Features
========

* Complete subscription/desubscription process, with confirmation emails.

* Completely decoupled, no need to modify your own code to use it, only
``settings.py`` and redefine templates as needed.

* Newsletters in HTML and plain text in the same email.

* Three different periods: daily, weekly and monthly newsletters, easily
configurable.

* Integrated with Django's admin.

* Optional reviewing process (in the admin).

* Cron scripts included.

* Unit tests included.


Installation
============

1. Include ``boletin`` in ``settings.INSTALLED_APPS``.

2. Create DB tables with ``python manage.py syncdb``.

3. Configure settings (see `Configuration`_ section).

4. Install cron scripts in the system's cron installation for automated
newsletter creation and (optionally) automated sending.
See "Cron configuration" below for more information.


Configuration
=============

You can configure many aspects of the behavior of the application via
settings variables. Mandatory variables are marked with (*).


NEWSLETTER_EMAIL (*)
--------------------

Email address from where to send the newsletter. Newsletter recipients
will see this address in the e-mail message "From" field.

Default: None, it's mandatory.

Example::

NEWSLETTER_EMAIL = '[e-mail]'


NEWSLETTER_REVIEWER_EMAIL
-------------------------

Email address for the newsletter reviewer. When a newsletter is generated,
an e-mail will be sent to this address prompting to the revision of the
newsletter.

Default: None.

Example::

NEWSLETTER_REVIEWER_EMAIL = '[e-mail]'


NEWSLETTER_REVIEWER_ADMIN_LINK
------------------------------

Relative URL suffix for newsletter objects in the admin application. The site
domain and the newsletter id will be, respectively, prepended and appended to
this string. This setting is optional; if not defined, the e-mail message to
the reviewer will not include a link to the admin application.

Default: None.

Example::

NEWSLETTER_REVIEWER_ADMIN_LINK = '/admin/boletin/newsletter/'

NEWSLETTER_GENERATOR_FUNCTION (*)
---------------------------------

This variable is a string pointing to a function inside the project which
will be responsible for retrieving content for inclusion in each newsletter.

The function must receive two parameters: ``from_date`` and ``to_date``, which define
the datetime range of the newsletter being created.

Default: None, it's mandatory.

Example::

NEWSLETTER_GENERATOR_FUNCTION = 'portal.newsletter.generate_content'

And the content of portal/newsletter.py::

from app1.models import FooModel
from app2.models import BarModel

def generate_content(from_date, to_date):
app1 = FooModel.objects.filter(date__gte=from_date, date__lte=to_date)
app2 = BarModel.objects.filter(date__gte=from_date, date__lte=to_date)
return {'app1': app1, 'app2': app2}


NEWSLETTER_PERIODS
------------------
Available newsletter periods in the project. It's a list with one or more of
'D' (daily), 'W' (weekly) and 'M' (monthly).

Default: ``['W']`` (only weekly newsletter)

Example::

NEWSLETTER_PERIODS = ['D', 'W', 'M'] # daily, weekly and monthly newsletters


Management commands
===================

Three management commands are included:

* ``createnewsletter``

* ``sendnewsletter``

* ``shownewsletter``

Createnewsletter
----------------

Generate a new newsletter for the given period (daily, weekly or monthly), both
in HTML and plain text. It renders the `templates`_ ``newsletter_email.html``
and ``newsletter_email.txt``.

Options:

* ``-d``, ``--daily``: daily period.

* ``-w``, ``--weekly``: weekly period.

* ``-m``, ``--monthly``: monthly period.

* ``-p``, ``--print``: print the created newsletter to stdout.

* ``-r``, ``--regenerate``: create the newsletter again if it already exists.

One and only one of ``-d``, ``-w`` or ``-m`` must be given.

Sendnewsletter
--------------

Send newsletters to subscribers.

Options:

* ``-n``, ``--newsletter``: send only the newsletter with the given ID.

* ``-f``, ``--force-unreviewed``: send unreviewed newsletters.

Without parameters all **reviewed** newsletters with pending sendings are
sent. Use the ``-f`` switch to send unreviewed newsletters (useful for a
completely automatic newsletter system). Use the ``-n`` switch to send an
specific newsletter. The `shownewsletters`_ command should be useful to see
created newsletters, their IDs and pending statuses.

Shownewsletters
---------------

Show stored newsletters, with their object ID (*different than their newsletter
number*) and pending status.

Options:

* ``-p``, ``--only-pending``: show only newsletters with pending sendings.

Templates
=========

Default templates are provided for the subscription and unsubscription process,
but you should redefine at least ``newsletter_email.txt`` and
``newsletter_email.html``. You can redefine any template creating a newsletter
dir inside your templates directory, copying the app template inside it and
changing that copy.

The available templates are:

* ``newsletter_base.html``: base template for the subscription and
unsubscription process, except email templates.

* ``newsletter_confirm_email.txt``: email template for confirming subscription.

* ``newsletter_confirm.html``: page telling the user the subscription
confirmation email has been sent to her email address.

* ``newsletter_email.html``: email template of a newsletter in email format.
You should redefine this depending on the context returned by the
``NEWSLETTER_GENERATOR_FUNCTION``.

* ``newsletter_email.txt``: same as newsletter_email.html, but in plain text.

* ``newsletter.html``: subscription/unsubscription form.

* ``newsletter_success.html``: subscription success page.

* ``newsletter_unsubscription_confirm_email.txt``: same as
newsletter_confirm_email, but for unsubscription.

* ``newsletter_unsubscription_confirm.html``: same as newsletter_confirm,
but for unsubscription.

* ``newsletter_unsubscription_success.html``: same as newsletter_success,
but for unsubscription.

Cron configuration
==================

There are several crontab files inside the ``cron`` directory that you can
simply include in your system-wide cron configuration to have automatic
newsletter creation and/or sending. The ``createnewsletter`` and
``sendnewsletter`` commands are smart enough to ignore petitions for unallowed
periods (i.e. not configured in `NEWSLETTER_PERIODS`_).

Development
===========

You can get the last bleeding edge version of boletin by doing a checkout of
trunk in its subversion repository::

svn checkout https://svnpub.yaco.es/djangoapps/boletin/trunk boletin

Bug reports, patches and suggestions are more than welcome. Just put
them in our Trac system and use the 'boletin' component when you fill
tickets::

https://tracpub.yaco.es/djangoapps/


Changes
=======

0.5.1 (2009-05-20)
------------------
- Fixed several bugs that rendered the application unusable. They all came from
the fact that the application changed name just before release, and some imports
were left unchanged.

0.5.0 (2009-05-18)
------------------
- Initial release