Files

Ryan Moon 5aadd68128 Add email system planning doc for transactional and mass email

Provider abstraction (SMTP, SendGrid, SES, Postmark), email templates with
merge fields, BullMQ queue for async sending, mass email campaigns with
recipient filtering, CAN-SPAM unsubscribe management, email logging.

2026-03-28 15:38:54 -05:00

11 KiB

Raw Permalink Blame History

Music Store Management Platform

Email System — Transactional & Mass Email

Version 1.0 | Draft

1. Overview

The email system handles all outbound email from the platform — both automated transactional messages (receipts, reminders, notifications) and bulk mass emails (announcements, promotions, newsletters). Like file storage, the email provider is abstracted behind an interface to support multiple backends.

2. Email Provider Interface

2.1 Providers

2.2 Configuration

Variable | Description | Default EMAIL_PROVIDER | smtp, sendgrid, ses, postmark | smtp EMAIL_FROM_ADDRESS | Default sender address | noreply@{company domain} EMAIL_FROM_NAME | Default sender name | {Company Name} SMTP_HOST | SMTP server hostname | (required if smtp) SMTP_PORT | SMTP port | 587 SMTP_USER | SMTP username | (required if smtp) SMTP_PASS | SMTP password | (required if smtp) SMTP_SECURE | Use TLS | true SENDGRID_API_KEY | SendGrid API key | (required if sendgrid) AWS_SES_REGION | SES region | (required if ses) AWS_SES_ACCESS_KEY | SES access key | (required if ses) AWS_SES_SECRET_KEY | SES secret key | (required if ses) POSTMARK_API_KEY | Postmark server token | (required if postmark)

2.3 Interface

interface EmailProvider {
  send(message: EmailMessage): Promise<EmailResult>
  sendBatch(messages: EmailMessage[]): Promise<EmailResult[]>
}

interface EmailMessage {
  to: string | string[]
  from?: string       // overrides default
  replyTo?: string
  subject: string
  html: string
  text?: string       // plain text fallback
  tags?: string[]     // for tracking/categorization
  metadata?: Record<string, string>  // provider-specific metadata
}

interface EmailResult {
  success: boolean
  messageId?: string
  error?: string
}

3. Email Types

3.1 Transactional (System-Triggered)

These fire automatically based on business events. Each has a template and trigger condition.

3.2 Mass Email (Staff-Initiated)

Staff can send bulk emails to filtered recipient lists. These are NOT marketing automation — they're one-off announcements.

Use Cases:

Store sale or promotion announcement
Schedule change notification (holiday hours)
Rental program updates
Back-to-school instrument availability
Concert or event invitations
Policy changes

3.3 Recipient Lists

Mass emails target filtered lists built from account/member data:

Filter | Description All accounts | Every account with an email Active rentals | Accounts with active rental contracts Active lessons | Members with active lesson enrollments By instrument type | Members renting/owning specific instruments By school | Accounts linked to a specific school By category | Accounts that purchased from a product category By location | Accounts at a specific store location Tax exempt | Tax-exempt accounts only Custom | Staff-built filter with multiple criteria

4. Database Schema

4.1 email_template

Store-customizable email templates. System provides defaults, stores can modify.

4.2 email_log

Append-only log of every email sent. Used for troubleshooting, compliance, and deliverability monitoring.

4.3 email_campaign

Mass email campaigns.

4.4 email_unsubscribe

Opt-out tracking. Respects CAN-SPAM.

5. Merge Fields

Templates support merge fields that resolve at send time:

Field | Resolves To {{account_name}} | account.name {{account_email}} | account.email {{member_name}} | member.firstName + member.lastName {{company_name}} | company.name {{company_phone}} | company.phone {{company_email}} | company.email {{amount}} | Transaction/payment amount (formatted) {{date}} | Relevant date (formatted) {{instrument}} | Instrument description {{portal_url}} | Customer portal URL {{unsubscribe_url}} | One-click unsubscribe link (required for mass email)

Custom merge fields per template type (e.g. repair estimate has {{estimate_total}}, {{repair_description}}).

6. Email Queue

Emails are not sent synchronously from API routes. They're queued via BullMQ and processed by a worker.

6.1 Queue Flow

Business event fires (e.g. repair status changes to "ready")
Event handler creates an email job: emailQueue.add('send', { templateSlug, recipientAccountId, entityType, entityId, data })
Worker picks up the job
Worker resolves template + merge fields
Worker calls emailProvider.send()
Result logged to email_log
On failure: retry with exponential backoff (3 attempts over 1 hour)

6.2 Mass Email Flow

Staff creates campaign with content and filter criteria
Staff clicks "Send" (or schedules)
System resolves recipient list from filter criteria
Creates one job per recipient (batched, throttled)
Worker processes queue with rate limiting (avoid provider throttling)
Campaign status updated as batches complete
Unsubscribed addresses skipped automatically

6.3 Rate Limiting

7. Unsubscribe Management

7.1 Requirements (CAN-SPAM)

Every mass email includes an unsubscribe link
Unsubscribe is one-click (no login required)
Unsubscribe processed within 10 business days (we do it instantly)
Unsubscribed addresses never receive mass email
Transactional emails (receipts, billing) are exempt from unsubscribe

7.2 Unsubscribe Endpoint

GET /unsubscribe?token={signed_token}

Token encodes email + company_id, signed with JWT secret
No authentication required
Shows confirmation page
Inserts into email_unsubscribe table
Returns "You've been unsubscribed" page

8. Admin UI

8.1 Email Templates Page

List all templates with status (active/inactive)
Edit template: subject, HTML body, text body
Preview with sample data
Reset to system default

8.2 Mass Email Page

Create campaign: subject, body (rich text editor), recipient filter
Preview recipient count before sending
Schedule or send immediately
Campaign history with sent/failed counts
View individual send status

8.3 Email Log

Searchable log of all sent emails
Filter by template, status, date, recipient
View email content as sent
Resend failed emails

9. Implementation Order

EmailProvider interface with SmtpProvider
email_template table + seed system templates
email_log table
BullMQ email queue + worker
Transactional triggers (start with receipt + repair ready)
Template editor in admin UI
email_campaign + email_unsubscribe tables
Mass email UI (create, filter, send)
Additional providers (SendGrid, SES, Postmark)
Email log viewer in admin UI

10. Business Rules

Emails are always queued, never sent synchronously from API routes
Failed emails retry 3 times with exponential backoff
Unsubscribed addresses are never sent mass email — checked at send time
Transactional emails always send regardless of unsubscribe status
All emails logged with full content for compliance
Email templates are company-scoped — each store customizes their own
Mass emails require at least one unsubscribe link in the body
Email provider is set at startup via env var — same as storage provider
BullMQ uses the same Valkey instance as the rest of the application
Mass email campaigns are rate-limited per provider to avoid throttling
Empty recipient lists block campaign send with clear error

11 KiB Raw Permalink Blame History