The mail system

← Previous Next →
Site Operations · 3 of 6

The mail system

Seven endpoints, one provider, no npm packages, and the reason a link in an email never does anything on its own

All outbound mail goes through Resend's REST API, called directly with fetch. No npm package and no build step, which matters because this site has neither. Cloudflare's own tutorial uses the resend SDK; that would require a build pipeline for the sake of one HTTP call.

The seven endpoints

RouteMethodSends
/api/contactPOSTNotification to you, receipt to the visitor
/api/newsletterPOSTSignup alert to you, confirmation to the subscriber
/disconnectGET then POSTUnsubscribe alert to you
/api/obituaryPOSTContribution to you, thank-you to the writer (the private remembering page)
/api/boffo-downloadPOSTDetails to you, download-page link to the visitor (the coupon on the Boffo page)
/api/boffo-invitePOST, then GET and POSTRequest to you with Approve buttons and a receipt to the visitor; on approval, the visitor's personal invitation link
/api/boffoPOSTA review email to you for every demo reading, follow-up and piece of feedback; nothing to the visitor

Contact, newsletter, obituary and the Boffo download check the visitor with Cloudflare Turnstile (functions/lib/turnstile.js). The Boffo demo and the invitation request do not: the demo is gated by invitation codes, and the request form by a hidden trap field and daily limits. Each route is one file under functions/api/, listed in worker.js.

Each handler validates input, escapes anything user-supplied before it reaches an HTML email body, and logs provider errors server-side while returning a vague message to the page. Provider detail never reaches a visitor.

Two-leg sends and what counts as success

Signup sends two emails: the alert that constitutes the actual record, and a courtesy confirmation to the subscriber. If the confirmation fails after the alert already succeeded, the visitor still gets a success response. Making them retry would produce a second alert for one real signup. The failure is logged, not surfaced.

The reverse case aborts. If the alert fails, no confirmation is attempted and the visitor sees an error, because nothing was recorded.

Why unsubscribe takes two steps

Key rule

A bare GET is fired by things that are not people: link checkers, crawlers, corporate mail scanners that fetch every URL in an incoming message, and browser prefetchers. Never let a GET perform an action.

This is not hypothetical here. A demo page on this site contained a hardcoded unsubscribe link with a placeholder address, neo@matrix.com. Crawlers following that link generated genuine "unsubscribe requested" emails, over months, for an address that had never subscribed. It looked like hostile traffic. It was a link on the site pointing back at the site.

So /disconnect now answers a GET with a confirmation page and sends nothing. Only the POST from that page's button sends the alert. RFC 8058 defines one-click unsubscribe as POST for exactly this reason. Links already sent in old emails still work; they simply land on the confirm page.

The Boffo invitation's Approve buttons follow the same rule. A button opens a page that shows the request and asks for confirmation; only that page's POST creates the code and emails the visitor. Each button is signed, works once, and expires with the request after 30 days.

Unsubscribe does not remove anyone

Worth being clear: there is no subscriber list in this system. Unsubscribe emails you so you can remove the address from wherever you actually track subscribers. Real automated removal would need a store behind the route, such as Cloudflare KV or D1. Until then, the step is manual and that is by design, not by oversight.

Deliverability

The sending domain is verified in Resend through DKIM, SPF and DMARC records in Cloudflare DNS. Confirmation emails carry a List-Unsubscribe header, which mail providers weigh heavily. The current setup scores 10/10 on mail-tester.

The free tier allows 100 emails a day, shared across every endpoint. The Boffo demo is the heaviest user: one review email per reading, follow-up and piece of feedback, with up to 60 readings a day site-wide. Worth remembering: an endpoint that emails on demand is a quota you do not fully control, which is another argument for keeping GET inert.