Phase 09: Email Dispatcher

Status: Not started Depends on: Phase 8 (Billing Engine)

Goal

Ensure all automated emails (invoices, low credits, license expiry, monthly reports, welcome) send correctly via SMTP with proper HTML templates. Add an email delivery log visible to super admin, and a test-email endpoint to verify SMTP config.

Planned Scope

Backend

Jinja2 HTML email templates (backend/app/templates/email/)

invoice.html — branded invoice notification (already plain text in Phase 8; upgrade to HTML)
low_credit_alert.html — low credit warning with credit meter visual
license_expiry.html — license expiry countdown with days remaining
monthly_report.html — monthly report summary email (stub, filled in Phase 11)
welcome.html — welcome email with license key + setup instructions (used in Phase 14)
Base layout template with consistent header/footer

email_logs table (new model app/models/email_log.py)

id, school_id (nullable), to_email, subject, email_type, status (sent/failed), sent_at, error_message, created_at

app/services/email.py — enhanced

Accept HTML template name + context instead of raw body string
Log every send attempt to email_logs table
Retry on transient failure (up to 3 attempts)

backend/app/routers/email.py (new)

GET /api/email-logs — super admin: paginated email delivery history with filters
POST /api/email/test — send a test email to verify SMTP config (super admin)

Update all tasks that send email (billing, sms, license) to use HTML templates

Frontend

EmailLogsPage or section in super admin

Table: to, subject, type, status badge, sent_at, error message
Filter by email type + status

api.ts additions

getEmailLogs(params) — list email logs
sendTestEmail(to) — trigger test email

Key Files to Create/Modify

backend/app/models/email_log.py (new)
backend/app/templates/email/*.html (new — 5 templates)
backend/app/services/email.py (enhance)
backend/app/routers/email.py (new)
backend/app/main.py — include email router
backend/migrations/versions/002_email_logs.py (new migration)
frontend/src/pages/EmailLogsPage.vue (new or section in existing page)
frontend/src/lib/api.ts — add email log functions
frontend/src/router/index.ts — add email logs route
frontend/src/components/sidebar/AppSidebar.vue — add nav item