DEV Community: Frank Mendez

🚀 Building a Newsletter Subscription Feature That Actually Works (No BS Edition)

Frank Mendez — Tue, 21 Apr 2026 09:14:33 +0000

The Problem With Most “Newsletter Features”

Let’s be honest—most newsletter setups are either:

Overkill (hello 20-step Mailchimp workflows)
Manual (someone forgets to hit “send”)
Or duct-taped together like a weekend hackathon project

What we actually want is simple:

User subscribes → You publish → Email goes out automatically

That’s it. No ceremony.

🧠 The Approach: Keep It Lean

This feature was built into a Blog CMS with a few strict rules:

No new vendors (use existing stack)
No double opt-in friction
Fully automated sending
One-click unsubscribe (because lawsuits are expensive 😅)

👉 Full design spec:

⚙️ Core Architecture

Instead of relying on external newsletter platforms, this setup runs fully in-house:

Database: Supabase
Email: Resend
Scheduler: Vercel Cron
Frontend: Next.js

Flow (a.k.a. “what actually happens”)

User enters email → stored in DB
Admin publishes a post
System schedules a send (with delay)
Cron job runs every minute
Emails are sent automatically
User can unsubscribe with one click

No dashboards. No manual triggers. No “oops we forgot to send.”

🗄️ Data Model (Simple but Powerful)

Two tables. That’s it.

1. `newsletter_subscriptions`

Tracks subscribers:

email (unique)
subscribed_at
unsubscribed_at (null = active)
unsubscribe_token (for one-click unsubscribe)

2. `newsletter_sends`

Acts like a queue:

post_id (1 send per post)
scheduled_at
status (pending → sending → sent/failed)

This separation is key. It lets you:

Schedule emails
Retry failures
Track delivery

⏱️ The Secret Sauce: Delayed Sending

Instead of blasting emails immediately:

NEWSLETTER_DELAY_MINUTES=60

Why this matters:

Gives you time to fix mistakes after publishing
Avoids “oops typo in production” emails
Feels more intentional

🔁 Automation via Cron

A Vercel cron job runs every minute:

* * * * * → /api/newsletter/cron

It checks:

Any pending sends?
Is scheduled_at <= now()?

If yes:

Mark as sending
Fetch active subscribers
Send emails
Update status

If something crashes midway?

👉 Anything stuck in sending for 10+ minutes is marked as failed

No silent failures. No ghost jobs.

✉️ Subscription Experience (UX Matters)

The Subscribe Form

Placed at the bottom of every blog post:

Email input
Subscribe button
Instant feedback (success or error)

No confirmation email. No friction.

Because let’s be real—every extra step kills conversions.

❌ Unsubscribe (Don’t Mess This Up)

Every email includes:

/api/newsletter/unsubscribe?token=xxx

Click → done.

No login. No “are you sure?” guilt trips.

Just clean, respectful UX.

🛡️ Edge Cases You’ll Actually Hit

Handled upfront:

Scenario	Result
Duplicate email	“Already subscribed”
Re-subscribe	Reactivates user
Invalid token	404
No subscribers	Send marked as complete
Cron crash	Auto-mark failed

This is where most systems break. Don’t skip it.

🧪 Testing Strategy

Because “it works on my machine” isn’t a strategy:

Unit tests: subscribe/unsubscribe logic
Integration tests: cron + email dispatch
E2E tests: full user flow

Yes, even for a “simple” feature.

💡 Why This Approach Wins

Let’s compare:

Approach	Reality
Mailchimp	Expensive + overkill
Manual send	Someone forgets
Zapier hacks	Fragile
This system	Clean, automatic, predictable

You control everything. No black boxes.

🧠 Final Thoughts

This isn’t just a newsletter feature—it’s an event-driven system disguised as one.

Publish event → triggers queue
Queue → processed by cron
State machine → tracks delivery

It’s simple on the surface, but solid under the hood.

And that’s the sweet spot.

🔥 If You’re Building Something Similar…

Start here:

Keep your data model clean
Automate everything
Design for failure (because it will happen)
Avoid adding tools just because they exist

🏁 TL;DR

If your newsletter requires manual effort, it’s broken.

Automate it. Keep it lean. Ship it.

Notifying Admins When Users Confirm Their Email — The Right Way with Supabase and Next.js"

Frank Mendez — Thu, 16 Apr 2026 10:12:24 +0000

Full blog => here
Steps (Article Sections)

Hook / Problem Statement — Why polling or signup-time notifications are wrong; email confirmation is async and outside your app's request cycle.
Architecture Overview — The 6-step event chain diagram (confirmation link → auth.users.confirmed_at → Postgres trigger → public.profiles.confirmed_at → Supabase Database Webhook → Next.js API route). Why bridging via a public-schema table is necessary (Supabase webhooks can't observe auth.*).
The Data Layer — The add_confirmed_at_to_profiles migration: adding the nullable confirmed_at column and the Postgres AFTER UPDATE trigger function handle_user_confirmed() that syncs it. Key insight: OLD.confirmed_at IS NULL AND NEW.confirmed_at IS NOT NULL guard.
The Webhook API Route — app/api/webhooks/user-confirmed/route.ts. Cover: shared-secret verification via x-webhook-secret header (security), parsing Supabase's { type, table, record } payload, independent try/catch per notification channel, and why always returning 200 OK prevents Supabase retry storms.
Notification Services — user-confirmed.ts. Resend for email (HTML body with name/email/ID/timestamp), Slack Incoming Webhook via fetch. Emphasize isolation — one failure never blocks the other.
Supabase Dashboard Config — The one-time manual step: create the DB webhook pointing to the deployed route, set the header, add a confirmed_at IS NOT NULL filter to reduce noise.

supabase.com
Environment Variables — Table of the 4 new vars (RESEND_API_KEY, ADMIN_EMAIL, SLACK_WEBHOOK_URL, WEBHOOK_SECRET) with descriptions.

What's Out of Scope (and Why) — No retry logic (intentional), no multi-admin, no notification prefs UI — acknowledge these and link to potential follow-ups.
Closing — Summary of the pattern: Postgres trigger → public table → Supabase webhook → app route. Reusable for other auth events (password reset, MFA enrollment, etc.).

Supabase Database Webhook Setup

User Confirmed Notification Webhook

This webhook fires when a user confirms their email and triggers admin notifications (email + Slack).

One-time setup in Supabase Dashboard

Go to Database → Webhooks in the Supabase Dashboard
Click Create a new hook
Fill in the following fields:

Field	Value
Name	`user-confirmed-notification`
Table	`public.profiles`
Events	`UPDATE`
Type	HTTP Request
Method	POST
URL	`https://your-domain.com/api/webhooks/user-confirmed`

Under HTTP Headers, add:

Header	Value
`x-webhook-secret`	(value of your `WEBHOOK_SECRET` env var)

Click Confirm to save.

Required: add confirmed_at filter

Without this filter, the webhook fires on every profile update (role changes, name updates, etc.), causing duplicate notifications. Add this filter condition:

Column: confirmed_at
Operator: is not
Value: null

This ensures the webhook only fires when confirmed_at is set.

Required environment variables

Make sure these are set in .env.local (dev) and in your Vercel / hosting environment (prod):

RESEND_API_KEY=
RESEND_FROM_EMAIL=
ADMIN_EMAIL=
SLACK_WEBHOOK_URL=
WEBHOOK_SECRET=

🚀 I Built a Full-Stack Blog CMS with Next.js + Supabase (And You Can Use It Today)

Frank Mendez — Wed, 15 Apr 2026 09:20:09 +0000

Updated October 26, 2026 — refreshed features, stack, setup, and links.

TL;DR: I built an open-source blog CMS with Next.js, Supabase, and TipTap. It now includes a richer publishing workflow, comments and reactions, author profiles, newsletters, and account security features. The live site is The Practical Engineer.

An important update for returning readers: the standalone AI assistant and external Developer API described in the original article have been retired. Personal AI provider settings remain available; editor assistance is future work.

🤔 Why I Built This

I wanted a practical place to write and publish without rebuilding authentication, permissions, an editor, and media handling for every project.

That idea grew into a full-stack CMS. The interesting work has increasingly been in the details: keeping drafts private, protecting published URLs, recovering writing, and making publication and newsletter delivery behave predictably when requests fail.

If you are learning Next.js and Supabase, those are useful problems to explore in a real codebase.

🧠 What the CMS Can Do Today

🔐 Accounts, roles, and security

The app uses Supabase Auth with email/password authentication and support for Google and GitHub sign-in when configured. It includes email confirmation, password recovery, authenticator-based MFA, and onboarding for new accounts.

Authors manage their own posts. Administrators manage users, posts, comments, and taxonomy. Authorization combines database Row Level Security with server-side identity, ownership, and role checks. Public author profiles expose a limited public view while private account data stays separate.

✍️ A fuller writing and publishing workflow

The TipTap rich-text editor supports formatting, links, tables, task lists, and images. Authors can organize posts with existing categories and searchable tags, add cover and inline images, and configure SEO metadata.

The workflow includes:

Draft saving, writing recovery, and a private preview of unsaved content.
A publication review step with server-side readiness checks and explicit human editorial confirmation.
Atomic post and taxonomy saves, plus conflict detection to protect against stale edits.
Published URL protection: changing an article URL is deliberate, and former published URLs redirect to the current one.
Search, filters, sorting, pagination, and bulk unpublish/delete actions in the dashboard.

Previewing does not make a draft public or send a newsletter. Publishing checks content readiness, but a human still needs to review accuracy, usefulness, attribution, and metadata.

💬 Community and discovery

Comments are now implemented, along with comment reactions and five article reaction types: Love, Unicorn, Mind blown, Celebrate, and Fire.

Readers can explore public author profiles and category/tag pages. The app also includes reading-time estimates, SEO metadata, canonical URLs, and sitemap support. Comments and SEO are no longer just items on the original wishlist.

📬 Newsletter subscriptions

Readers can subscribe from article pages. Publishing queues a newsletter notification through Resend with a configurable delay. The default delay is 60 minutes; delivery starts on a subsequent dispatcher run, rather than being guaranteed exactly an hour later.

Authors can see notification status in the editor. Unpublishing cancels pending delivery, and administrators have a newsletter dashboard with subscriber information and CSV export. Messages include unsubscribe links.

🤖 What changed with AI and the API?

The standalone PDF upload, book chat, and full-post generation workflows are retired. The external Developer API and developer-key interface are retired too; old endpoints return 410 API_RETIRED.

Authors and administrators can still manage their own encrypted provider credentials in Settings → AI Providers. Credential verification checks provider access; it does not generate content. Administrators do not get access to another author's provider keys.

Editor assistance is tracked separately as future work. This project should no longer be described as offering a supported headless API or a working standalone AI writing assistant.

For details, see AI Providers and retirement and Developer API retirement.

🛠️ Current Tech Stack

These are the versions pinned in the repository when this update was written, rather than a claim about the latest upstream releases.

Area	Technology
Application	Next.js 16.4.2 App Router, React 19.3.1, TypeScript 6.0.3
Database, auth, media	Supabase Postgres, Auth, Storage, and RLS
Rich-text editor	TipTap 3.31.4
UI	Tailwind CSS 4.3.3, shadcn/ui, Base UI, Lucide icons
Forms and validation	React Hook Form and Zod
Client state	Zustand
Email	Resend
Testing	Vitest, Testing Library, and Playwright
Deployment	Vercel, with cron-based newsletter dispatch
Local toolchain	Node 24.21.0 and pnpm 10.29.3

OpenAI, Anthropic, and Google SDK dependencies remain in the repository for provider settings and future work. Their presence does not mean content generation is currently available.

🚀 Run It Locally

You will need the pinned Node and pnpm versions, plus Docker for local Supabase.

git clone https://github.com/thepracticalengineer/nextjs-blog-cms.git
cd nextjs-blog-cms
nvm install
nvm use
corepack enable
pnpm install --frozen-lockfile
pnpm dlx supabase@2.119.0 start

Then follow the local development guide to configure your local Supabase credentials and environment. Use the complete ordered migration history; the historical schema snapshot alone is not enough.

Once configuration is ready:

pnpm run dev

Open http://localhost:3000. Use a disposable local database for tests and keep server-side secrets out of client code and Git.

The testing guide covers unit and browser/API verification. For deployment, read the migration prerequisites and deployment guide.

🧭 What’s Next

The current roadmap includes:

Editor assistance.
An analytics dashboard.
Scheduled article publication.
Multi-author collaboration.

These are planned features. Newsletter dispatch scheduling already exists, but scheduled article publication is a separate capability.

Check the roadmap and GitHub issues for the evolving status.

📦 Open Source — Try It, Fork It, Improve It

The project is MIT-licensed. Use it as a starting point for your own blog or to study how an App Router application handles publishing, permissions, rich text, and background email delivery.

If you try it, I would love feedback on the writing experience and the parts that are confusing. Bug reports and focused contributions help make it better.

⭐ Star or fork the repository

Happy building 👨‍💻