# Bulk Gmail Mailer — Production Build

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

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

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

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

## E. Tests & Docs
- [ ] E1. pytest suite (OAuth, tokens, CSV/TXT, validation, variables, invoice gen, uniqueness, PDF, MIME, retry, rotation, clear-all, etc.)
  - [x] test_variable_engine.py (21) — invoice format, collision, ranges, substitution, analysis
  - [x] test_recipient_service.py (35) — parse txt/csv, aliases, validation, 2000 cap
  - [x] test_message_builder.py (28) — MIME, attachments, List-Unsubscribe, PDF, sanitize
  - [x] test_security_rotation.py (51) — Fernet, bcrypt, JWT, classify_error, RotationAssigner, selectors
  - [x] test_gmail_service.py (28) — client json, state, auth URL, token exchange/refresh, SMTP XOAUTH2
  - [x] test_api_recipients_subjects_templates.py (41) — auth/CSRF/recipients/subjects/templates APIs
    - App fixes driven by tests: CSRF added to 25 endpoints (recipients/subjects/templates/logout), empty-subject validation, google_start honest 400, TXT import header-skip bug
  - [ ] test_api_attachments_phones_suppression_settings_logs.py
  - [ ] test_api_accounts_campaigns_testsend_unsubscribe.py
  - [ ] test_campaign_engine.py (materialization, sequencing, uniqueness)
  - [ ] test_send_one_task.py (retry/backoff/DLQ, statuses, mocked Gmail)
  - [ ] test_sse_dashboard.py
- [ ] 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