websauna.newsletter 1.0a3

Installing Python package

Install this package using pip.

Setup newsletter renderer

You need to register a site specific newsletter that is responsible for rendering your newsletter HTML payload. Do this in your Initializer.configure_views. Example:

# Configure newsletter renderer
from mysite.views.newsletter import NewsletterRenderer
from websauna.newsletter.interfaces import INewsletterGenerator
registry = self.config.registry
registry.registerAdapter(factory=NewsletterRenderer, required=(IRequest,), provided=INewsletterGenerator)

For more information see demo.py.

Unsubscription link

In your renderer HTML code you can use Mailgun unsubscription management:

<p class="details">
  {# For Mailgun #}
  <a href="%mailing_list_unsubscribe_url%">Unsubscribe from TokenMarket newsletter.</a>
</p>

Setting up the secrets

Add Mailgun API keys and such in myapp/conf/development-secrets.ini.

Example:

[mailgun]
# Get from Mailgun
api_key = x

# What is the mailing list we use in the test suite
mailing_list = unit-testing@mailgun.websauna.org

# Outbound domain used for the newslettering
domain = mailgun.websauna.org

# From: email we use to send the newsletter
from = MyApp Newsletter <newsletter-demo@websauna.org>

Create Mailgun mailing list object

Easiest to do this through ws-shell using production configuraition:

ws-shell tokenmarket/conf/production.ini

Then using %cpaste notebook shell command:

from websauna.system.core.utils import get_secrets
from websauna.newsletter.mailgun import Mailgun
secrets = get_secrets(request.registry)
list_address = secrets["mailgun.mailing_list"]
mailgun = Mailgun(request.registry)
mailgun.create_list(list_address, "MyApp newsletter")

You get a reply:

{'list': {'access_level': 'readonly',
  'address': 'newsletter@example.com',
  'created_at': 'Wed, 25 Jan 2017 17:08:56 -0000',
  'description': 'TokenMarket newsletter',
  'members_count': 0,
  'name': ''},
 'message': 'Mailing list has been created'}

Integration subscription for on your site

A boostrap based mini subscription form is provided with the packag. It is ideal e.g. to place in the site footer.

Simply in your template do:

<h3>Follow</h3>
{% include "newsletter/subscription_form.html" %}

For more information run the demo and view demotemplates/site/footer.html.

Sending and preview

Visit Newsletter tab in the admin interface to preview and send out newsletters.

Resetting the news collection date

You can manually set the newsletter state, when the last newsletter was sent, from shell:

import datetime
from websauna.newsletter.state import NewsletterState

state = NewsletterState(request)
state.set_last_send_timestamp(datetime.datetime(2016, 12, 24).replace(tzinfo=datetime.timezone.utc))

State is managed in Redis.

Exporting subscribers

In console:

from websauna.system.core.utils import get_secrets
from websauna.newsletter.mailgun import Mailgun
secrets = get_secrets(request.registry)
list_address = secrets["mailgun.mailing_list"]
mailgun = Mailgun(request.registry)
print(mailgun.list_members(list_address))  # TODO: pagination

Importing email subscribers

Note that importing website users is supported in the admin interface.

Example:

subscribers = """
mikko@example.com
pete@example.com
"""

from websauna.system.core.utils import get_secrets
from websauna.newsletter.mailgun import Mailgun
from websauna.newsletter.views import subscribe_email

secrets = get_secrets(request.registry)
list_address = secrets["mailgun.mailing_list"]
mailgun = Mailgun(request.registry)

for s in subscribers.split():
    s = s.strip()
    if s:
        subscribe_email(request, s)

Manually testing with Celery

Make sure Celery is not eager in development.ini:

websauna.celery_config =
    {
        "broker_url":  "redis://localhost:6379/15",
        "task_always_eager": False,
    }

Start demo (Terminal 1):

pserve ws://websauna/newsletter/conf/development.ini

Start Celery (Terminal 2):

ws-celery  ws://websauna/newsletter/conf/development.ini -- worker

1.0a3 (2018-10-03)

• After subscription, redirect user back to original url.

• Support for Python 3.7.

1.0a2 (2018-04-22)

• Fix missing ‘namespace_packages’.

1.0a1 (2018-03-06)

• Initial Release