firehose/investigation/question-3-email-subscriptions.md

Question 3: Email Subscriptions — Investigation

1. Does any email subscription functionality already exist?

No. Zero. The codebase contains no newsletter, subscription, or subscriber functionality whatsoever.

A grep for newsletter, subscrib, subscriber, unsubscribe across all .ex and .heex files in the project returned zero matches.

2. What existing email infrastructure is already in place?

Mailer (Swoosh)

• File: app/lib/firehose/mailer.ex (line 1-3)
• Uses Swoosh.Mailer, otp_app: :firehose
• Config uses Swoosh.Adapters.Local in dev (config.exs, line 40)
• Config uses Swoosh.Adapters.Test in test (test.exs, line 24)
• Production uses Swoosh.Adapters.SMTP via env vars (runtime.exs, lines 54-65)

UserNotifier (existing pattern for transactional emails)

• File: app/lib/firehose/accounts/user_notifier.ex
• Has two notification functions:
  • deliver_update_email_instructions/2 (line 41)
  • deliver_login_instructions/2 (line 53) — which dispatches to either deliver_confirmation_instructions or deliver_magic_link_instructions
• Internal deliver/4 helper (line 19) constructs a Swoosh.Email, calls Mailer.deliver/1
• Uses SENDER_NAME and SMTP_FROM_EMAIL env vars (lines 12-13)
• Only sends plain-text emails (no HTML templates)

Accounts Context

• File: app/lib/firehose/accounts.ex
• Has deliver_user_update_email_instructions/3 and deliver_login_instructions/2
• Uses UserToken.build_email_token/2 for token generation (hashed tokens stored in DB)
• Token expiry: 15 minutes for magic links, 7 days for email change

Production SMTP config (runtime.exs, lines 46-64)

Uses env vars:

• SMTP_HOST, SMTP_PORT, SMTP_USERNAME, SMTP_PASSWORD, SMTP_SSL, SMTP_TLS

No Oban or background job system

• mix.exs has no Oban dependency
• No GenServer for background email sending
• app/lib/firehose/application.ex — no Oban or job queue in the supervision tree
• Current mailer calls are synchronous (not ideal for bulk sending)

3. What database tables exist?

Only one migration exists:

File: app/priv/repo/migrations/20260401201722_create_users_auth_tables.exs

Two tables:

• users — id, email (citext, unique), hashed_password, confirmed_at, timestamps
• users_tokens — id, user_id (FK), token (binary), context (string), sent_to (string), authenticated_at (utc_datetime), inserted_at (timestamps, no updated_at)

No subscriber table, no subscription table, no newsletter table exists.

4. What would a minimal email subscription feature need?

4.1 Database Model

New table: subscribers

Column	Type	Purpose
id	bigserial	PK
email	citext, unique, not null	Subscriber email
confirmed_at	utc_datetime, nullable	Set when double opt-in confirmed
unsubscribed_at	utc_datetime, nullable	Set when unsubscribed
token	binary, nullable	Confirmation token (hashed)
token_inserted_at	utc_datetime, nullable	When token was created
inserted_at	utc_datetime	Timestamps
updated_at	utc_datetime	Timestamps

The confirmed_at field is the canonical way to know if a subscription is active (following the same pattern as users.confirmed_at).

4.2 Migration

Would create the subscribers table with:

• citext extension already exists (from the users migration, line 4)
• Unique index on email
• Index on confirmed_at for querying active subscribers

4.3 Subscription Form

Where to place it:

• Homepage (app/lib/firehose_web/controllers/page_html/home.html.heex) — add a "Subscribe to newsletter" section
• Blog index page (app/lib/firehose_web/controllers/blog_controller.ex) — could also have a subscription form
• Footer of the layout (app/lib/firehose_web/components/layouts/app.html.heex) — persistent subscription form

Form would POST to a new SubscriptionController (or use a LiveView component).

4.4 Confirmation Email Flow (Double Opt-In)

1. User enters email on subscription form
2. Server creates subscriber record with confirmed_at: nil, generates a hashed confirmation token
3. Server sends confirmation email with a link like GET /newsletter/confirm/:token
4. User clicks link → confirmed_at is set → subscription is active
5. User can unsubscribe via GET /newsletter/unsubscribe/:token (or a link in each email)

Pattern to follow: The existing UserToken + UserNotifier pattern in app/lib/firehose/accounts/user_token.ex shows how tokens are built, hashed, stored, and verified. The subscriber confirmation flow would be simpler — no need for the full context system, just a single-purpose token.

4.5 Sending New Posts to Subscribers

Options (in order of complexity):

1. Simple GenServer — Polls for new published posts every N minutes, sends to confirmed subscribers. No external dependency, but no retry/backoff.
2. Oban — Background job queue. Add {:oban, "~> 2.18"} to mix.exs. Schedule a recurring job (via Oban.Cron) to check for new posts and enqueue delivery jobs. Provides retries, observability, and proper error handling.
3. Manual trigger — When a post is published (from the editor dashboard), fan out to subscribers. Requires hooking into the post-publishing flow.

Recommendation: The GenServer approach is simpler, but Oban is more robust. The current codebase has no background job system, so either would be an addition.

How to know which posts are new: The Blogex system compiles posts at build-time from markdown files, so there's no "published_at" event. A polling approach would need to track which posts have already been sent (e.g., a sent_posts table tracking post_id + sent_at).

4.6 Unsubscribe Mechanism

• Each email would include a link like https://example.com/newsletter/unsubscribe?token=<token>
• The token is a hashed version of the subscriber's ID or a dedicated unsubscribe token
• Clicking the link sets unsubscribed_at and the subscriber is excluded from all future sends
• No login required — one-click unsubscribe

4.7 New Files Needed

File	Purpose
app/lib/firehose/newsletter/subscriber.ex	Ecto schema for subscribers table
app/lib/firehose/newsletter.ex	Context module (CRUD, subscribe, confirm, unsubscribe)
app/lib/firehose/newsletter/notifier.ex	Email sending (confirmation, new post)
app/priv/repo/migrations/*_create_subscribers.exs	Migration
app/lib/firehose_web/controllers/newsletter_controller.ex	Handle confirm/unsubscribe links
OR app/lib/firehose_web/live/newsletter_live.ex	LiveView component for subscription form
app/lib/firehose/newsletter/sender.ex	GenServer or Oban worker for sending to subscribers

5. Roughly how complex is this? Estimate the scope.

Complexity: Medium (roughly 2-3 days of focused work)

Breakdown by layer:

Layer	Effort	Details
DB schema + migration	1-2 hours	Simple table, following existing patterns
Ecto schema + context	2-3 hours	CRUD, changeset validations, subscribe/confirm/unsubscribe
Confirmation email flow	2-3 hours	Token generation, email sending, link handling
Subscription form UI	2-3 hours	Form on homepage, validation, success/error states
Unsubscribe mechanism	1-2 hours	Token-based one-click unsubscribe
Email sending to subscribers	4-6 hours	The bulk of the work — polling mechanism, tracking sent posts, formatting emails
Tests	3-4 hours	Following existing test patterns in accounts_test.exs
Total	~15-22 hours

Risk factors:

• The blog posts are compiled at build-time, so there's no "post published" event to hook into. A polling mechanism or a manual "send to subscribers" button in the editor dashboard would be needed.
• No background job system exists — either Oban needs to be added (additional dependency, migration) or a simpler GenServer approach is used.
• Sending bulk emails from a single-threaded GenServer could block. Oban would handle this properly with concurrent workers.

Simpler alternative (MVP): A "Subscribe to newsletter" form that stores emails, with a manual CSV export workflow. No automated sending. This would be ~half the effort but would not be a real solution.

6. Existing patterns to follow

User Auth Token Pattern (for confirmation tokens)

File: app/lib/firehose/accounts/user_token.ex

The UserToken module shows:

• Tokens are generated with :crypto.strong_rand_bytes(32) (line 58)
• Tokens are hashed with :crypto.hash(:sha256, token) before storage (line 79)
• Raw tokens are Base64-url-encoded for URLs (line 80)
• Verification decodes, re-hashes, and queries the database (lines 97-112)
• Context system distinguishes token types (e.g., "session", "login", "change:email")

For subscriber confirmation, we could either:

• Reuse users_tokens table with a new context like "subscribe_confirm"
• Create a simpler token field directly on the subscribers table

The simpler approach (token field on subscribers table) is recommended to avoid coupling to the auth system.

User Notifier Pattern (for email sending)

File: app/lib/firehose/accounts/user_notifier.ex

The deliver/4 function (line 19) constructs a Swoosh.Email:

defp deliver(recipient, subject, body) do
  email = new() |> to(recipient) |> from(sender()) |> subject(subject) |> text_body(body)
  with {:ok, _metadata} <- Mailer.deliver(email), do: {:ok, email}
end

A newsletter notifier would follow this pattern exactly, possibly adding HTML body support.

Accounts Context Pattern (for CRUD operations)

File: app/lib/firehose/accounts.ex

The Accounts context module shows the standard pattern:

• Repo.get_by/3 for lookups
• changeset + Repo.insert/1 for creation
• Repo.transact/1 for transactional operations
• Repo.update/1 for updates
• Function naming convention: subscribe/1, confirm_subscriber/1, unsubscribe/1

Scope Pattern (for authorization)

File: app/lib/firehose/accounts/scope.ex

For newsletter subscriptions, scopes aren't directly relevant (subscribers are anonymous). But the pattern shows how struct-based contexts are used.

Migration Pattern

File: app/priv/repo/migrations/20260401201722_create_users_auth_tables.exs

The migration shows:

• execute "CREATE EXTENSION IF NOT EXISTS citext", "" (line 4) — already exists
• create table(:users) with timestamps(type: :utc_datetime) (line 6)
• create unique_index(:users, [:email]) (line 11)

Test Fixture Pattern

File: app/test/support/fixtures/accounts_fixtures.ex

Shows the fixture pattern:

• unique_user_email/0 — generates unique emails using System.unique_integer()
• valid_user_attributes/1 — merges defaults with overrides
• user_fixture/1 — creates a real DB record

Summary

Email subscriptions do not exist in any form. The infrastructure is there (Swoosh mailer, SMTP config, email sending patterns), but the feature is a clean-slate addition. The heaviest part would be the automated sending of new posts to subscribers, which requires either adding Oban or building a polling GenServer, and solving the "which posts are new" problem since posts are compiled at build-time rather than published at runtime.