Newsletter¶

Any blog can also be a newsletter. Readers subscribe, confirm by email, and receive posts as issues.

Turn it on by editing the blog and ticking Newsletter enabled. A Subscribe link then appears on the blog, and /blog/<slug>/subscribe/ starts accepting signups.

Before your first send¶

Read this part. Everything below it is easy; this part is where newsletters actually go wrong.

Set your site URL. Every issue contains an unsubscribe link built from it. If it still resolves to localhost, every link in the send is dead — and a send cannot be recalled. The app refuses to queue in that state; set SITE_DOMAIN (or SITE_URL) first.

Set up SPF, DKIM and DMARC for your sending domain. No amount of code substitutes for this. Without it a few thousand messages land in spam, and you will not find out from any log — only from readers who never got it.

Consider a separate mailer for bulk. The Mailer alias field picks a second entry from your MAILERS setting, so a 5,000-recipient send doesn't share an IP and domain reputation with your password-reset emails.

Send yourself a test copy. It is the only way to catch a rendering or header problem before subscribers see it.

How subscribing works¶

1. A reader enters their address.
2. They get a confirmation email. They are not subscribed yet.
3. They click it, confirm, and receive a welcome email.

This is double opt-in, and it's on by default. It protects you from someone signing up an address they don't own, and it is what keeps a list deliverable.

The signup page says the same thing whether or not an address is already subscribed — otherwise the form becomes a way to test whether a given person reads your blog.

Sending an issue¶

From a post, use Send as newsletter — that creates a draft issue. Or create one directly under Blog → Issues with its own subject and body.

On the issue page:

1. Send test copy to yourself.
2. Send to subscribers — this freezes the content and the audience, and starts delivery.

From that moment the issue is a permanent record: editing the post later does not change what was sent, and the issue can no longer be edited.

Delivery runs in the background in batches. The page shows progress, and Stop sending halts what hasn't gone out yet. Copies already delivered cannot be recalled.

If some deliveries fail, Retry failed deliveries re-queues the ones worth retrying. It never re-sends to anyone who already received it.

Sending needs a worker running (manage.py db_worker). Without one, an issue sits at "queued" and nothing happens — /smallstack/status/ reports it.

Unsubscribing¶

Every issue carries a one-click unsubscribe button that mail clients show next to the sender's name, plus a link in the footer. Both work without the reader signing in, and the unsubscribe link in an old email keeps working forever.

Unsubscribing never deletes the record — that's how we remember someone opted out, so a later list import can't quietly add them back.

Bounces¶

If an address is rejected outright, it's suppressed and receives nothing further. A temporary failure (a dropped connection, a greylist) is retried and does not suppress anyone; only a run of consecutive failures eventually does. Staff can clear a suppression under Blog → Subscribers.

Importing a list¶

manage.py blog_import_subscribers <blog> list.csv --consent-note "..."

The consent note is required, because importing is the one path that skips confirmation: you are asserting these people already agreed, and the record of why needs to exist before the first send rather than be reconstructed afterwards. Without --confirmed, imported addresses still have to confirm.

Don't import a list you bought, or addresses collected for something else. It is the fastest way to get a sending domain blocked.