# Product Requirements Document (PRD)

## Product
- **Name:** Email Campaigner
- **Version:** Draft v0.1
- **Date:** 2026-03-31
- **Status:** Working draft based on repository analysis

## Scope of this PRD
- Define requirements for a web-based email campaign platform.
- Cover campaign creation, audience management, template editing, sending, tracking, and basic transactional email operations.
- Capture the current product baseline and the target outcomes for near-term releases.

## Assumptions (to be confirmed)
- Product is a multi-user internal/SMB tool for marketing and communication teams.
- Primary channels are bulk campaigns and basic transactional sends.
- Backend uses API services with database persistence and SMTP-based delivery.
- Frontend is a protected dashboard application with authenticated access.

## Problem Statement
Teams need a single, simple interface to manage audience lists, design email content, send campaigns reliably, and measure performance without stitching together multiple disconnected tools.

## Goals
- Reduce campaign launch time from idea to send.
- Improve delivery reliability and visibility into send outcomes.
- Centralize contact/list management and template reuse.
- Provide actionable analytics for opens, clicks, and conversions (where available).
- Maintain compliance basics (unsubscribe, suppression, tracking consent support).

## Non-Goals (Current Phase)
- Advanced marketing automation/journey orchestration.
- AI-generated campaign copy.
- Enterprise-grade segmentation engine and predictive analytics.
- Native mobile application.

## Target Users
- **Marketing manager:** Creates and schedules campaigns, tracks outcomes.
- **Campaign operator:** Builds templates, imports contacts, executes sends.
- **Admin:** Manages settings, sender identity, and access controls.

## User Stories
- As a user, I can reset a forgotten password using an email link so I can regain access without an administrator.
- As a campaign operator, I can create a campaign from a reusable template so I can send faster.
- As a marketer, I can upload/import contacts and organize them into lists for targeted sends.
- As a marketer, I can send a test email before publishing a campaign.
- As a marketer, I can launch a campaign and monitor send status.
- As a marketer, I can view opens/clicks and compare campaign performance.
- As a recipient, I can unsubscribe from future campaign emails.

## Functional Requirements

### 1) Authentication and Access
- Secure sign-in required for all product areas except login, sign-up, and password-recovery routes.
- Authenticated routing for dashboard and feature modules.
- Sign-out and session state handling.
- **Forgot password:** User requests a reset link from the login screen (email only). Supabase GoTrue sends a recovery email; the link opens `/reset-password` where the user sets a new password and is then signed in. Redirect URL must be allow-listed in Supabase Auth settings (e.g. `http://localhost:8098/reset-password` for Docker dev).

### 2) Dashboard
- Overview cards for campaign and audience health.
- Quick links to build/send workflows.
- Recent activity and high-level performance metrics.

### 3) Campaign Management
- Create, edit, view, and list campaigns.
- Set campaign metadata: name, subject, sender name, sender email, reply-to.
- Associate a campaign with a contact list and a template.
- Support campaign statuses (e.g., draft, sending, sent, failed where applicable).
- Support full-screen campaign builder/editor flow.

### 4) Template Management
- Create and maintain reusable templates.
- Edit template content with merge fields.
- Preview rendered template content.
- Reuse one template across multiple campaigns.

### 5) Contact and List Management
- Create and manage contacts with custom fields.
- Maintain subscription status per contact.
- Create/manage lists and map contacts to lists.
- Contact detail view with history context.
- CSV import support for bulk contact ingestion.

### 6) Sending and Delivery
- Send test emails to a specified address.
- Send campaigns to subscribed contacts in selected list.
- Track recipient state (pending/sent/failed).
- Batch sending with throttling controls.
- Idempotency for recipient insertions and send safety where possible.

### 7) Tracking and Analytics
- Track sent/open/click-related events where implemented.
- Link rewriting for click tracking.
- Open tracking pixel support.
- Campaign analytics pages and details.

### 8) Unsubscribe and Compliance Baseline
- Include unsubscribe link in outgoing campaign email context.
- Respect unsubscribed recipients in campaign sends.
- Emit list-unsubscribe headers.

### 9) Transactional Email (Basic)
- Dedicated section for transactional sends/config.
- Ability to manage non-campaign email workflows at a basic level.

### 10) Settings
- App-level settings for sender/company defaults.
- Environment-aware configuration behavior.

## Non-Functional Requirements
- **Performance:** UI interactions should remain responsive for standard marketing team workflows.
- **Reliability:** Sending should handle partial failures and continue processing remaining recipients.
- **Security:** Auth-protected app areas; secure handling of SMTP credentials and secrets.
- **Scalability:** Batch send pipeline should support incremental scaling without full rearchitecture.
- **Observability:** Errors and send failures should be logged for debugging.
- **Usability:** Workflow should allow new users to execute first campaign with minimal training.

## Success Metrics (Initial)
- Time to first campaign sent.
- Campaign send success rate.
- Failure rate by send batch and recipient.
- Open rate and click-through rate trends.
- Unsubscribe rate and spam complaint indicators (if available).
- Monthly active operators.

## Release Plan

### Phase 1 (Current Baseline Stabilization)
- Authenticated app shell and navigation.
- Campaigns, contacts, lists, templates, analytics, settings pages.
- Basic campaign sending with test send and tracking events.

### Phase 2 (Operational Hardening)
- Better retry/queue controls for sending.
- Enhanced analytics fidelity and filtering.
- Data validation and import UX improvements.
- Permission model refinement.

### Phase 3 (Growth Features)
- Segmentation improvements.
- Scheduling and optimization enhancements.
- Expanded transactional capabilities and templates.

## Risks and Mitigations
- **Deliverability risk:** Configure sender domain and monitor bounce/complaint patterns.
- **Data quality risk:** Add import validation and duplicate-handling rules.
- **Compliance risk:** Ensure unsubscribe and suppression handling is enforced in send path.
- **Operational risk:** Add retry, monitoring, and alerting around send failures.

## Dependencies
- SMTP provider availability and configuration.
- Database performance and integrity for recipient/event tracking.
- Frontend/backend API contract stability.
- Email template rendering and merge field consistency.

## Open Questions
- What is the primary customer profile (internal team, agencies, SMB SaaS)?
- Which compliance standards are mandatory (GDPR, POPIA, CAN-SPAM)?
- Is scheduling required in the immediate release scope?
- What are target send volumes per hour/day?
- Is role-based access control needed now or later?
- Should transactional email be full feature parity or remain basic?

## Acceptance Criteria (PRD Draft Completion)
- PRD reviewed by product and engineering stakeholders.
- Goals, scope, and release phases agreed.
- Open questions resolved or assigned owners and due dates.
- Success metrics approved and instrumentable.

## Appendix: Inferred Current Feature Surface
- Authenticated routes and protected layouts.
- Pages for dashboard, campaigns, contacts, lists, templates, analytics, transactional, settings.
- Campaign/test send service with batching, template compilation, link rewriting, tracking pixel injection, recipient status updates, and event logging.

---

## Addendum (2026-04-15): AI enrichment & conversational delivery

### Goals
- Rewrite each outgoing campaign email per recipient using an LLM (OpenAI GPT-4o) so copy feels like a one-to-one note, with configurable tone and sender instructions.
- Require explicit **batch approval** of enriched variants before send.
- Support a shared operational mailbox (e.g. `sammy@ourdrives.co.za`) via Microsoft 365 SMTP for enriched sends.
- Prefer **reply-based unsubscribe** for enriched sends when enabled: omit `List-Unsubscribe` header; detect “unsubscribe” via keywords first, then LLM for ambiguous replies; auto-reply with a configurable (optionally LLM-polished) message and mark the contact unsubscribed.
- **Forward** non-unsubscribe inbound replies to configurable addresses (per campaign), with optional **BCC** on all enriched sends.

### Data model
- `contacts.enrichment_data` (JSONB) — extra context for the model (role, company notes, Apollo exports, etc.).
- `campaign_settings` — enrichment toggles, tone, instructions, send-from overrides, reply-unsubscribe flags, templates, forward/BCC lists.
- `campaign_enriched_emails` — original vs enriched subject/body, review status, outbound `Message-ID` for threading.
- `inbox_messages` — classified inbound mail and forward audit trail.

### API surface (high level)
- `PUT /api/campaigns/:id/settings`, `GET /api/campaigns/:id/settings`
- `POST /api/campaigns/:id/enrich` (async job)
- `GET /api/campaigns/:id/enriched`, approve/reject endpoints, `POST /api/campaigns/:id/send-enriched`
- `GET /api/campaigns/:id/inbox`

### Non-goals (this phase)
- Native Apollo API integration (data is stored manually / via import in `enrichment_data`).
- Guaranteed legal compliance in all jurisdictions — operators remain responsible for consent and commercial email rules.