​

Email Unsubscribe System Documentation

​

Overview

​

Email Categories

​

1. Marketing Emails (Can Unsubscribe) ✅ ACTIVE

• ✉️ feature_announcements - New feature announcements and product updates
• ✉️ marketing_general - General marketing communications, webinars, and promotional content

​

2. Operational Emails (Managed in Settings UI) ✅ ACTIVE

• 📊 emailDailySummary - Daily portfolio snapshots (via all_users table)
• 📈 emailStockPriceSpikes - Stock price movement alerts
• 💳 emailSpendingSpikes - Spending spike alerts
• 📄 emailFinancialStatementSchedule - Scheduled financial statements

​

3. Transactional Emails (Always Sent) ✅ ACTIVE

• 🔒 security - Security alerts and 2FA
• 👋 welcome - Welcome and onboarding emails
• 🗑️ account_deletion - Account deletion confirmations
• ⚠️ error_notifications - Critical error alerts

​

User Experience Flow

​

Marketing Email Unsubscribe

1. User receives marketing email (e.g., feature announcement, webinar invite)
2. Clicks “Unsubscribe from marketing emails” link at bottom
3. Automatically unsubscribed from BOTH marketing email types:
   • feature_announcements = false
   • marketing_general = false
4. Sees confirmation page explaining they’ll still receive:
   • Daily financial snapshots (if enabled)
   • Important account and security notifications
5. Can manage detailed preferences in Settings → Email Notifications

​

Marketing Email Management in Settings

1. User goes to Settings → Email Notifications
2. Can toggle individual marketing preferences:
   • ☑️ Feature Announcements - New features, product updates, improvements
   • ☑️ Marketing & Promotions - Webinars, office hours, educational content
3. Both have blue “Marketing” badges to distinguish from operational emails

​

Operational Email Management

1. User goes to Settings → Email Notifications
2. Can toggle individual preferences:
   • ☑️ Portfolio Summary (Daily)
   • ☑️ Spending Alerts (Weekly)
   • ☑️ Stock Price Alerts (Daily)
   • ☑️ Personal Financial Statement (Scheduled)
3. These are independent of marketing email preferences

​

Technical Implementation

​

Permission Check Before Sending

// Check if user allows this email type
const canSend = await emailSubscriptionManager.canSendEmail(
  clerkId,
  'marketing_general'
)

if (!canSend) {
  // Skip this user
  continue
}

​

Generate Unsubscribe Link

// Generate secure token and unsubscribe URL
const unsubscribeLink = await emailSubscriptionManager.generateUnsubscribeLink(
  clerkId,
  'marketing_general'
)

// Include in email footer
<Link href={unsubscribeLink}>Unsubscribe from marketing emails</Link>

​

Using Marketing Preferences in Settings UI

// In your settings component
import { useMarketingPreferences } from '@/hooks/queries/use-marketing-preferences'

const {
  preferences, // { feature_announcements: boolean, marketing_general: boolean }
  isLoading,
  updatePreference, // (field, value) => Promise<void>
  isUpdating
} = useMarketingPreferences()

// Toggle a preference
<Switch
  checked={preferences.feature_announcements}
  onCheckedChange={(checked) =>
    updatePreference('feature_announcements', checked)
  }
  disabled={isLoading || isUpdating}
/>

​

Using Operational Email Preferences

// In your settings component
import { useEmailPreferences } from '@/hooks/queries/use-email-preferences'

const {
  preferences, // { emailDailySummary, emailSpendingSpikes, emailStockPriceSpikes }
  isLoading,
  updatePreference, // (type, value) => void
  isUpdating
} = useEmailPreferences()

// Toggle a preference
<Switch
  checked={preferences.emailDailySummary}
  onCheckedChange={(checked) =>
    updatePreference('emailDailySummary', checked)
  }
  disabled={isLoading || isUpdating}
/>

​

Processing Unsubscribe

1. Validates token (not expired, not used)
2. Checks if it’s a marketing email type
3. If marketing → disables BOTH marketing preferences
4. If operational → disables only that specific preference
5. Redirects to confirmation page

​

Database Schema

​

email_preferences table

-- Marketing (both disabled together via unsubscribe link)
feature_announcements BOOLEAN DEFAULT TRUE
marketing_general BOOLEAN DEFAULT TRUE

-- Note: Operational emails (daily summaries, alerts, etc.) are stored in all_users table,
-- not in email_preferences. They use different columns:
-- email_daily_summary, email_spending_spikes, email_stock_price_spikes, etc.

​

unsubscribe_tokens table

clerk_id TEXT NOT NULL
token TEXT NOT NULL UNIQUE
email_type TEXT NOT NULL
expires_at TIMESTAMPTZ NOT NULL (90 days)
used_at TIMESTAMPTZ (null until used)

​

Legal Compliance

​

CAN-SPAM Act ✅

• ✅ One-click unsubscribe in all marketing emails
• ✅ Clear “Unsubscribe” language
• ✅ Processes unsubscribe within 10 business days (instant)
• ✅ Physical address in footer (Silvia contact info)

​

GDPR ✅

• ✅ Users can manage all preferences
• ✅ Clear explanation of email types
• ✅ Easy opt-out mechanism
• ✅ No dark patterns

​

Best Practices ✅

• ✅ Protects operational emails users need
• ✅ Clear communication about what continues
• ✅ Settings page for granular control
• ✅ Transactional emails always sent

​

Email Footer Template

<footer>
  You received this email because you signed up for Silvia.
  <br />
  <a href="{unsubscribeLink}">Unsubscribe from marketing emails</a> | 
  <a href="https://cfosilvia.com/settings">Manage email preferences</a>
  <br />
  Note: You'll still receive important account notifications and daily portfolio updates (if enabled).
</footer>

​

Key Files

​

Backend

• /lib/email-subscription-manager.ts - Core EmailSubscriptionManager class
• /app/api/unsubscribe/route.ts - Unsubscribe token processing
• /app/api/marketing-preferences/route.ts - Marketing preferences CRUD
• /sql-queries/email-preferences-schema.sql - Database schema

​

Frontend

• /app/settings/page.tsx - Settings page with email preference toggles
• /app/unsubscribe/page.tsx - Unsubscribe confirmation page
• /hooks/queries/use-marketing-preferences.ts - Marketing preferences hook
• /hooks/queries/use-email-preferences.ts - Operational email preferences hook

​

Email Templates

• /emails/feature-announcement-email.tsx - Feature announcement template
• /emails/daily-email.tsx - Daily portfolio summary template

​

Testing Checklist

• Run SQL schema to create tables
• Test unsubscribe link generation
• Verify marketing email disables both marketing prefs
• Verify operational emails still work after unsubscribe
• Check confirmation page displays correctly
• Verify expired tokens are rejected
• Verify used tokens can’t be reused
• Test permission checks skip unsubscribed users

​

API Routes

​

Unsubscribe System

• GET /api/unsubscribe?token=xxx - Process unsubscribe token and redirect to confirmation
• POST /api/unsubscribe - Alternative POST method for unsubscribe

​

Marketing Preferences Management

• GET /api/marketing-preferences - Fetch user’s marketing email preferences
• PATCH /api/marketing-preferences - Update marketing preferences (feature_announcements, marketing_general)

​

Email Sending

• GET /api/email/feature-announcement?secretKey=xxx - Send feature announcement emails
• GET /api/email/daily?secretKey=xxx - Send daily portfolio summaries

​

Implemented Features

• ✅ Email preference management UI in settings (both marketing and operational)
• ✅ Marketing preferences API endpoint
• ✅ Granular toggles for all email types
• ✅ Toast notifications on preference changes
• ✅ Real-time preference updates

• Resubscribe flow for users who change their mind
• Email frequency controls (e.g., digest mode)
• A/B testing for unsubscribe language
• Analytics dashboard for email preferences
• Email preview before scheduling

​

How to Send a Marketing Email (Complete Example)

// Example: Sending a feature announcement email
import { emailSubscriptionManager } from '@/lib/email-subscription-manager'
import { resend } from '@/lib/resend'
import FeatureAnnouncementEmail from '@/emails/feature-announcement-email'

export async function sendFeatureAnnouncement(userId: string, userEmail: string) {
  // 1. Check if user allows this email type
  const canSend = await emailSubscriptionManager.canSendEmail(
    userId,
    'feature_announcements'
  )
  
  if (!canSend) {
    console.log(`User ${userId} has unsubscribed from feature announcements`)
    return { skipped: true }
  }
  
  // 2. Generate unsubscribe link for this email
  const unsubscribeLink = await emailSubscriptionManager.generateUnsubscribeLink(
    userId,
    'feature_announcements'
  )
  
  // 3. Send email with unsubscribe link
  const { data, error } = await resend.emails.send({
    from: 'Silvia <no-reply@cfosilvia.com>',
    to: userEmail,
    subject: 'New Feature: Enhanced Account Types',
    react: FeatureAnnouncementEmail({ unsubscribeLink }),
  })
  
  if (error) {
    console.error('Failed to send email:', error)
    return { error }
  }
  
  return { success: true, messageId: data.id }
}

​

Summary