Hey ${escapeHtml(data.name)}, welcome to Elon AI!
${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`: ```typescript 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 ```typescript // 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: `${escapeHtml(data.message)}
${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`: ```typescript 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 ```typescript 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: ```bash pnpm email:preview ``` ## Security Requirements ### XSS Protection **ALWAYS** use `escapeHtml()` on user-controlled content: ```typescript // CORRECT - escaped${escapeHtml(data.userName)}
// WRONG - XSS vulnerability!${data.userName}
``` ### 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`: ```typescript // 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 = `