Elon AI Email Templates

Overview

HTML string-based email templates for the Elon AI Classroom Assistant platform. This project does NOT use React Email components - all templates are pure HTML strings with TypeScript helper functions.

Important: The global react-email skill documents React Email patterns. This project uses a different approach optimized for simplicity and performance. Follow this skill for Elon AI email work.

When to Use

• Creating new transactional email templates

• Modifying existing templates in email-send.ts

• Understanding the email queue architecture

• Adding new email types to the system

Architecture

Email Flow

API/Action → publishJob({jobType: "email:send"}) → Upstash QStash (queue) → emailSendHandler() → Template selection (EMAIL_TEMPLATES[templateId]) → HTML string generation → Resend API → User inbox

Key Files

File Purpose

lib/jobs/handlers/email-send.ts

All 12 email templates + handler (916 lines)

lib/email/constants.ts

Centralized colors, styles, logo URL

lib/email/unsubscribe-token.ts

HMAC-signed unsubscribe tokens

app/api/email/unsubscribe/route.ts

Unsubscribe API endpoint

lib/jobs/types.ts

EmailSendPayloadSchema definition

.email-previews/

HTML preview files for visual testing

Template Pattern

All templates use pure HTML strings with helper functions:

// Template structure in EMAIL_TEMPLATES object welcome: (data) => ({ subject: "Welcome to Elon AI!", html: wrapInBaseTemplate({ headerTitle: Welcome, ${escapeHtml(data.name)}!, headerSubtitle: "Your AI-powered study companion is ready", content: <p style="${STYLES.bodyText}"> Hey ${escapeHtml(data.name)}, welcome to Elon AI! </p> ${createButton("Get Started", url)} , proTip: "Your conversations are FERPA-protected.", }), }),

Helper Functions

Function Purpose Example

wrapInBaseTemplate()

Header + content + footer wrapper See above

createButton()

Primary/secondary CTA buttons createButton("Click Me", url, "primary")

createInfoBox()

Key-value info cards createInfoBox([{label: "Name", value: "John"}])

escapeHtml()

XSS protection for user content escapeHtml(user.name)

Style Constants

All styles are defined in STYLES object at top of email-send.ts :

const STYLES = { container: "...", // Max-width 600px centered layout header: "...", // Maroon gradient header headerTitle: "...", // White text for header body: "...", // White background body bodyText: "...", // Gray text paragraphs button: "...", // Maroon primary button buttonSecondary: "...", // White bordered button infoBox: "...", // Gray background info card proTipBox: "...", // Gold accent tip box footer: "...", // Gray footer // ... more };

Existing Templates (12)

Template ID Purpose Key Data Fields

welcome

New student onboarding name

role_change

User role changed userName , oldRole , newRole

assistant_published

Teacher's assistant goes live assistantName , courseName , joinCode

budget_warning

Admin usage alert percentUsed , currentSpend , budgetLimit

processing_failed

File upload error fileName , errorMessage

new_student_joined

Admin notification studentName , studentEmail , joinedAt

role_request

Admin action needed userName , userEmail , requestedRole

role_approved

Role request approved name , newRole , tips[] , dashboardUrl

role_denied

Role request denied name , requestedRole , reason

teacher_digest

Weekly analytics totalSessions , uniqueStudents , satisfactionRate , topTopic

qr_join_code

QR code invitation assistantName , courseName , joinCode , qrCodeUrl

Adding a New Template

Step 1: Add to EMAIL_TEMPLATES object

// In lib/jobs/handlers/email-send.ts

const EMAIL_TEMPLATES = { // ... existing templates

// Your new template my_new_template: (data) => ({ subject: Your subject with ${escapeHtml(data.dynamicValue)}, html: wrapInBaseTemplate({ headerTitle: "Header Title", headerSubtitle: "Optional subtitle", content: <p style="${STYLES.bodyText}"> ${escapeHtml(data.message)} </p> ${createButton("Action", data.actionUrl)} , proTip: "Optional helpful tip", }), }), };

Step 2: Add payload schema (if needed)

If your template needs specific data validation, update lib/jobs/types.ts :

export const EmailSendPayloadSchema = z.object({ tenantId: z.string().uuid(), templateId: z.string(), // Template ID to: z.string().email(), subject: z.string().optional(), // Override template subject data: z.record(z.unknown()), // Template-specific data });

Step 3: Trigger the email

import { publishJob } from "@/lib/jobs/publisher";

await publishJob({ jobType: "email:send", payload: { tenantId: user.tenantId, templateId: "my_new_template", to: user.email, data: { message: "Hello world!", actionUrl: "https://elon-ai.app/action", }, }, });

Step 4: Generate preview

Add test data and regenerate previews:

pnpm email:preview

Security Requirements

XSS Protection

ALWAYS use escapeHtml() on user-controlled content:

// CORRECT - escaped <p>${escapeHtml(data.userName)}</p>

// WRONG - XSS vulnerability! <p>${data.userName}</p>

FERPA Compliance

• Include tenantId in all email payloads

• All sends are logged to audit_logs table

• Don't include student PII in email subjects

• Unsubscribe tokens use HMAC-SHA256 signing

Multi-Tenant Scoping

• Emails are always scoped to a tenant

• Job queue handles tenant isolation

• Audit logs record tenant context

Email Client Compatibility

DO

• Use PNG/JPG images with absolute URLs

• Use inline CSS styles (no classes)

• Use table-based layouts for columns

• Keep emails under 102KB

• Test in Gmail, Outlook, Apple Mail

DON'T

• Use SVG images (Gmail strips them)

• Use CSS Grid or Flexbox

• Use media queries (limited support)

• Use external CSS files

• Use JavaScript

Logo

The logo is a hosted PNG at public/email-assets/elon-ai-logo.png :

// Defined in lib/jobs/handlers/email-send.ts const EMAIL_LOGO_URL = "https://elon-ai.app/email-assets/elon-ai-logo.png"; const LOGO_IMG = <img src="${EMAIL_LOGO_URL}" alt="Elon AI" width="48" height="48" />;

To regenerate the logo PNG:

pnpm tsx scripts/generate-email-logo.ts

Testing

Visual Previews

Open .email-previews/index.html to browse all templates visually.

Unit Tests

pnpm test tests/unit/email/

Integration Tests

pnpm test tests/integration/api/unsubscribe.test.ts

Development Mode

When RESEND_API_KEY is not set, emails are logged to console instead of sent.

Brand Colors

Color Hex Usage

Maroon #73000a

Headers, buttons, primary text

Gold #b59a57

Accents, pro tips, highlights

White #ffffff

Body backgrounds, button text

Gray-50 #f9fafb

Footer, info box backgrounds

Gray-700 #374151

Body text

Common Patterns

Teacher Analytics Email

The teacher_digest template demonstrates advanced patterns:

• Dynamic headlines based on metrics

• Conditional content based on activity level

• Unsubscribe link with HMAC token

• Color-coded metric changes

QR Code Email

The qr_join_code template shows how to include images:

• Hosted QR code image URL

• Fallback text if image fails

• Clear call-to-action