# Bulk Gmail Mailer — Production Build

## A. Environment & Scaffolding
- [ ] A1. Install/verify PostgreSQL, Redis, Python deps (or document docker-compose path)
- [ ] A2. Project layout, pyproject/requirements, .env.example, config module
- [ ] A3. Database models (18 tables), migrations (Alembic), encryption layer (Fernet)
- [ ] A4. Security primitives: password hashing, JWT, CSRF, rate limiting, audit log, upload validation

## B. Core Backend
- [ ] B1. Auth: user registration/login, Google OAuth 2.0 start/callback (state verification), token storage encrypted
- [ ] B2. Gmail accounts manager: connect/test/reauthorize/disconnect (revoke tokens), Clear All, per-account limits
- [ ] B3. Gmail JSON/client-config import + validation (no secrets exposed), never plaintext
- [ ] B4. Recipients: manual/CSV/TXT import, validation (syntax, dupes, suppression, bounces), preview, max 2000
- [ ] B5. Subject lines manager (CRUD, search, import/export, Clear All)
- [ ] B6. HTML templates manager (paste/upload/editor/preview/duplicate/import/Clear All) + sanitization
- [ ] B7. Variable engine (all %vars%, custom CSV columns, unknown-var warnings)
- [ ] B8. Invoice number generator (configurable format, crypto-strong, collision check, per-campaign unique)
- [ ] B9. Random financial generators (RandomTotal, RandomShippingCharge, admin-configurable ranges)
- [ ] B10. Attachment system (types, HTML→PDF via WeasyPrint, unique filenames, malware-scan hook)
- [ ] B11. Company phone numbers manager (manual/CSV, selection rule) → %CompanyPhone%
- [ ] B12. Suppression list + unsubscribe flow (public tokenized link + POST /unsubscribe)
- [ ] B13. Campaign wizard (12 steps) + preview endpoint rendering real messages
- [ ] B14. Template sequencing modes (repeat/stop/random), subject rotation, account rotation (sequential/weighted, cooldown, per-account limits, auto-pause)

## C. Sending Engine
- [ ] C1. Celery app + queue config, per-recipient jobs, rate limiting, retry/backoff, DLQ, pause/resume/cancel
- [ ] C2. Real Gmail API send (OAuth2, MIME construction, message ID/thread ID capture) + OAuth2 SMTP alternative
- [ ] C3. Status model: queued/submitted/accepted/temp_failed/perm_failed/suppressed/bounced — no fake success
- [ ] C4. SSE live progress stream + campaign monitor endpoints
- [ ] C5. Send Test Email flow with provider-confirmed results
- [ ] C6. Campaign logs + CSV export

## D. Frontend
- [ ] D1. Layout, responsive CSS (13 nav pages), professional UI
- [ ] D2. Pages: Dashboard, Gmail Accounts, Recipients, Subject Lines, HTML Templates, Saved Templates, Attachments, Company Phones, Campaigns (wizard+monitor), Send Test, Logs, Suppression, Settings
- [ ] D3. Live progress via SSE, confirm dialogs for destructive ops

## E. Tests & Docs
- [ ] E1. pytest suite (OAuth, tokens, CSV/TXT, validation, variables, invoice gen, uniqueness, PDF, MIME, retry, rotation, clear-all, etc.)
- [ ] E2. Integration test gated on real Gmail credentials (skips otherwise)
- [ ] E3. Dockerfile, docker-compose (api/worker/postgres/redis), gunicorn/uvicorn prod config, HTTPS notes
- [ ] E4. README: Google Cloud OAuth setup, Gmail API setup, Postgres/Redis setup, workflow, compliance notes

## F. Verification & Delivery
- [ ] F1. Run full test suite + boot the app against real Postgres/Redis; verify endpoints/UI
- [ ] F2. Package source (zip) and deliver with docs