Build a Newsletter System

The newsletter system you can read in full and fix yourself at two in the morning

A subscriber replied to a campaign with a screenshot. The unsubscribe link in the footer returned a 404, and she had typed one line underneath it: “I clicked this four times.” That link was owned by a hosted platform, routed through their tracking domain, and when their route broke, recovery came down to a support ticket. Meanwhile the complaint sat in an inbox and a few more like it would push sender reputation into the range where messages route straight to spam.

That failure was not a content problem. The copy was fine, the offer landed. What broke was a piece of plumbing nobody could reach, owned by a vendor whose incentives stop at keeping their own platform up. A broken unsubscribe route on a system you own is a fifteen-minute fix. Five separate content sites, one backend on a sixth domain, one JavaScript file serving every site cross-origin — update the file once and every site updates at the same instant. The sites stay static and dumb; the backend holds all the logic and every credential. Per-subscriber pricing turns growth into a bill; a SQLite file does not care whether it holds two hundred rows or two hundred thousand.

Seven components from pipeline boundary to dispatch log

• the-pipeline — The six-stage boundary map: six separate PHP and Python files, each with one responsibility. The table that defines what each stage takes in, produces, and writes to the database — and why the boundary between signup and dispatch is the rule that keeps a change to one from corrupting the other.
• the-subscriber-backend — The SQLite schema and PHP API: the subscribers table, the status state machine (unconfirmed → confirmed → unsubscribed), and the endpoints that write and read each transition. The design that keeps confirmed addresses clean without a cron job.
• double-opt-in — The confirmation flow: HMAC-signed token generation, the confirm.php handler that validates and flips status, and the email copy that gets clicked. Why a confirmed subscriber is the only kind worth counting, and what a bounce looks like when the pipeline has boundaries.
• the-popup-component — The modal.js component: scroll-depth trigger, form rendering, cross-origin POST to the signup API, and the single deploy that updates every site. The configuration object that controls trigger depth, form fields, and redirect URL without touching the component itself.
• tracking — The pixel and click-tracker: p.php returns a 1×1 GIF and logs the open; t.php logs the click and redirects. The per-campaign attribution table, how open and click counts join to subscriber records, and why a tracker that logs failures is worth more than one that only logs success.
• unsubscribe — The signed unsubscribe route: HMAC token in the footer link, key rotation strategy, and the confirm page that sets status cleanly. Why a signed link that survives key rotation is cheaper to build once than to explain to a subscriber who clicked four times.
• dispatch — The Python dispatch script: confirmed-list query, rate limit as a first-class design constraint rather than a surprise discovered at send time, per-row send logging before the send happens, and the one rule that makes a stalled send recoverable without re-sending to subscribers who already received it.

A preview

If you built the system, you own the list, and you own the behavior. A broken unsubscribe route becomes a fifteen-minute fix you ship yourself, at two in the morning if that is when you catch it. That is more setup up front. The trade is that nothing about the system is waiting for someone else’s support ticket.

Per-subscriber pricing is the mechanism by which a list that grows turns into a bill that grows. A SQLite file does not care whether it holds two hundred rows or two hundred thousand. The ceiling you actually hit is the host’s outbound mail rate, and the dispatch chapter treats that as a first-class design constraint rather than a surprise discovered the night of a big send.

Anyone who wants to own the plumbing

This book is for newsletter operators who want to own the list, the behavior, and the infrastructure rather than rent access to all three from a hosted platform. It assumes you can read PHP and Python and know what a cron job is. It is not an introduction to email marketing — it is the construction guide for the system underneath it, built on ordinary shared hosting, with no per-subscriber pricing and no vendor whose support queue stands between you and a broken footer link.

A longer excerpt is available to newsletter subscribers.

Buy Ebook on Amazon