JAlcocerTech E-books

Consent and Email: Double Opt-In, Unsubscribe, Retention

Collecting an email address is easy. Being allowed to write to it, proving that you are, and stopping the moment you’re asked to: that’s the part most small sites skip, and the part a data-first business can’t.

I built it myself rather than adopting a newsletter platform, for one reason: the list stays mine, in the same pipeline as every other lead. The cost is owning the compliance features a platform would have provided. This chapter is that list of features.

A subscription isn’t real until the address owner confirms it. The Worker stores the lead as pending and sends a confirmation email with a link like:

https://www.example.com/api/forms/confirm?t=<payload>.<signature>

The token is stateless: the payload says which site, which email, which action and when it was issued, and the signature is an HMAC of that payload with a secret only the Worker (and the homelab) know. Nothing is stored per token, so there’s no table to clean up. Confirm links expire after 7 days; unsubscribe links never do.

Two details matter more than they look:

  • GET shows a page, POST acts. Corporate mail scanners open every link in an email to check it for malware. If opening the link confirmed the subscription (or unsubscribed someone), the scanner would do it. So the link opens a page with a button, and only the button’s POST changes anything.
  • Constant-time comparison of signatures, so timing can’t leak how much of a forged token was right.

Unsubscribe in one click, everywhere

Every marketing email carries a visible unsubscribe link and the headers that mail clients use for their own “Unsubscribe” button:

List-Unsubscribe: <https://www.example.com/api/forms/unsubscribe?t=…>
List-Unsubscribe-Post: List-Unsubscribe=One-Click

That’s RFC 8058, and large mailbox providers expect it from bulk senders.

One bug worth knowing about: Python’s email package folds long headers, and a long List-Unsubscribe URL got rewritten into an encoded form mail clients couldn’t use. Nothing failed; the button just never appeared. The fix was a policy with a longer line limit (SMTP.clone(max_line_length=998)). I found it by reading the raw message in a local test inbox (Mailpit).

A do-not-send list that stores no addresses

Unsubscribes, hard bounces and spam complaints all write to one suppression list in KV, keyed by the SHA-256 of the normalised address:

suppress:3f1a9c…   {"at":"2026-10-02T…","site":"www.example.com","source":"one-click"}

Every sender checks it immediately before every send, not when a sequence starts. Because it’s a hash, the list can survive an erasure request: the person’s data is deleted, but the fact “never email this address” remains, without the address. A new, explicit subscription clears the entry: that’s fresh consent.

The email provider’s event webhook feeds the same list, but only with permanent failures: hard bounces, spam complaints and blocks. A soft bounce (a full mailbox, a temporary error) shouldn’t silence someone forever.

Each site’s forms show consent text with a version (2026-10-01). The lead stores the version that was on screen. If the wording changes, old consents still point at what the person actually agreed to.

Two consent mistakes I made and fixed:

  • A bundled checkbox. The audit form had one required box that combined the terms of use with marketing consent, and promised an email that didn’t exist. Now it’s a required terms box and a separate, optional, unticked marketing box, and the code does exactly what the text says.
  • Retention that forgot status. Newsletter sign-ups had no expiry, which is right for confirmed subscribers but wrong for people who never confirmed. Now pending and unsubscribed entries expire after 30 days. Writing the privacy page is what exposed it: write the policy against the code, and you’ll find the gaps.

Sending: one adapter, swappable providers

Two places send email: the Worker (confirmation emails, within seconds) and the homelab (sequences). Both go through an adapter with one switch:

SettingUse
EMAIL_PROVIDER=mailjetProduction
EMAIL_PROVIDER=mailtrapAlternative provider, same code path
SMTP to MailpitLocal development: every email captured, none delivered

Provider quirks I hit, so you don’t have to:

  • “Accepted” isn’t “sent”. Mailjet answers 200 for the request and reports success per message; check each message’s status.
  • Turn tracking off per message if your privacy page says you don’t track opens and clicks. Account defaults can differ.
  • Sender validation needs a domain ownership record, separate from SPF and DKIM. Cloudflare’s DNS form placed it one level too high (at the zone root, not on the sending subdomain), and every email was held until it was moved.
  • Send from a subdomain (news.example.com) with SPF, DKIM and DMARC, so marketing reputation never touches the domain you reply from.

Sequences as files

Welcome emails and follow-ups are sequences defined in TOML files in the homelab repository, sent by a small standard-library Python engine:

  • a send ledger in SQLite, so no step is ever sent twice, even after a crash or a re-run;
  • the suppression check at the last moment, right before each send;
  • only to people with a basis: confirmed subscribers, or leads with recorded marketing consent, never “everyone who wrote in”;
  • sequences start disabled and are switched on only after the copy has been reviewed.

Testing on production without emailing strangers

An allow-list of test addresses forces double opt-in and the full email path for those addresses on the live sites, while real visitors are unaffected. That let me test the real chain end to end, from form to Worker, email, confirm link, homelab mirror and first sequence email, before switching it on for everyone.

Next: the homelab side.