# 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