# Email Template System - Product Requirements Document (PRD)

## 1. Executive Summary

This PRD outlines the requirements for a comprehensive email template management system that allows administrators to create, edit, customize, preview, and manage all email communications sent to users (customers) and organizers in the event management platform.

## 2. Objectives

- Provide a centralized system for managing all email templates
- Allow administrators to toggle email notifications on/off per role (Customer/Organizer)
- Enable template customization with dynamic variables
- Include site logo in all email templates
- Provide preview and test email functionality
- Ensure all templates are editable through the admin interface

## 3. Features Overview

### 3.1 Core Features
1. **Email Template Management**
   - Create, edit, and delete email templates
   - Support for HTML and plain text versions
   - Template preview functionality
   - Test email sending capability

2. **Role-Based Email Controls**
   - Admin can enable/disable emails per role (Customer/Organizer)
   - System-wide email toggle controls
   - Per-template enable/disable settings

3. **Template Customization**
   - Dynamic variable system
   - Site logo integration
   - WYSIWYG editor for template content
   - Subject line customization

4. **Email Settings**
   - Default sender information
   - Email footer customization
   - Branding elements (logo, colors)

## 4. Detailed Requirements

### 4.1 Email Templates

#### 4.1.1 Template Categories

**A. Authentication Templates**
1. User Registration Welcome (Customer)
   - Trigger: After customer registration
   - Recipient: Customer
   - Toggle: Admin → Customer emails

2. Organizer Registration Welcome
   - Trigger: After organizer registration
   - Recipient: Organizer
   - Toggle: Admin → Organizer emails

3. Email Verification
   - Trigger: User registration / resend verification
   - Recipient: User/Organizer
   - Toggle: Admin → Customer/Organizer emails

4. Password Reset Request
   - Trigger: User requests password reset
   - Recipient: User/Organizer
   - Toggle: Admin → Customer/Organizer emails

5. Password Changed Confirmation
   - Trigger: After password change
   - Recipient: User/Organizer
   - Toggle: Admin → Customer/Organizer emails

6. Account Suspended
   - Trigger: Admin suspends account
   - Recipient: User/Organizer
   - Toggle: Admin → Customer/Organizer emails

7. Account Reactivated
   - Trigger: Admin reactivates suspended account
   - Recipient: User/Organizer
   - Toggle: Admin → Customer/Organizer emails

**B. Organizer-Specific Templates**
8. Organizer Account Approved
   - Trigger: Admin approves organizer account
   - Recipient: Organizer
   - Toggle: Admin → Organizer emails

9. Organizer Account Rejected
   - Trigger: Admin rejects organizer account
   - Recipient: Organizer
   - Toggle: Admin → Organizer emails

10. Organizer Verification Pending
    - Trigger: Organizer submits verification documents
    - Recipient: Organizer
    - Toggle: Admin → Organizer emails

**C. Event-Related Templates**
11. Event Submitted for Approval
    - Trigger: Organizer creates new event
    - Recipient: Organizer
    - Toggle: Admin → Organizer emails

12. Event Approved
    - Trigger: Admin approves event
    - Recipient: Organizer
    - Toggle: Admin → Organizer emails

13. Event Rejected
    - Trigger: Admin rejects event
    - Recipient: Organizer
    - Toggle: Admin → Organizer emails

14. Event Suspended/Cancelled
    - Trigger: Admin suspends/cancels event
    - Recipient: Organizer
    - Toggle: Admin → Organizer emails

15. Event Reminder (to Attendees)
    - Trigger: X days before event (configurable)
    - Recipient: Customer (Attendees)
    - Toggle: Admin → Customer emails

16. Event Cancelled (to Attendees)
    - Trigger: Event is cancelled
    - Recipient: Customer (Attendees)
    - Toggle: Admin → Customer emails

17. Event Updated (to Attendees)
    - Trigger: Significant event details change
    - Recipient: Customer (Attendees)
    - Toggle: Admin → Customer emails

**D. Order & Ticket Templates**
18. Order Confirmation
    - Trigger: Order completed successfully
    - Recipient: Customer
    - Toggle: Admin → Customer emails

19. Ticket Purchase Confirmation
    - Trigger: Ticket purchase completed
    - Recipient: Customer
    - Toggle: Admin → Customer emails

20. Ticket Transfer Notification
    - Trigger: Ticket transferred to another user
    - Recipient: Customer (both original and new owner)
    - Toggle: Admin → Customer emails

21. Ticket QR Code Reminder
    - Trigger: Before event with QR code
    - Recipient: Customer
    - Toggle: Admin → Customer emails

**E. Payment Templates**
22. Payment Successful
    - Trigger: Payment confirmed
    - Recipient: Customer
    - Toggle: Admin → Customer emails

23. Payment Failed
    - Trigger: Payment failed
    - Recipient: Customer
    - Toggle: Admin → Customer emails

24. Payment Pending
    - Trigger: Payment awaiting confirmation
    - Recipient: Customer
    - Toggle: Admin → Customer emails

25. Refund Requested
    - Trigger: Refund request submitted
    - Recipient: Customer
    - Toggle: Admin → Customer emails

26. Refund Approved
    - Trigger: Admin approves refund
    - Recipient: Customer
    - Toggle: Admin → Customer emails

27. Refund Rejected
    - Trigger: Admin rejects refund
    - Recipient: Customer
    - Toggle: Admin → Customer emails

28. Refund Processed
    - Trigger: Refund completed
    - Recipient: Customer
    - Toggle: Admin → Customer emails

**F. Payout Templates (Organizer)**
29. Payout Requested
    - Trigger: Organizer requests payout
    - Recipient: Organizer
    - Toggle: Admin → Organizer emails

30. Payout Processing
    - Trigger: Admin processes payout
    - Recipient: Organizer
    - Toggle: Admin → Organizer emails

31. Payout Completed
    - Trigger: Payout successfully completed
    - Recipient: Organizer
    - Toggle: Admin → Organizer emails

32. Payout Failed
    - Trigger: Payout fails
    - Recipient: Organizer
    - Toggle: Admin → Organizer emails

**G. System Notification Templates**
33. New User Registered (Admin)
    - Trigger: New user registration
    - Recipient: Admin
    - Toggle: Admin → System emails (always on for admin)

34. New Organizer Application (Admin)
    - Trigger: New organizer registration
    - Recipient: Admin
    - Toggle: Admin → System emails (always on for admin)

35. New Event Submitted (Admin)
    - Trigger: New event submitted for approval
    - Recipient: Admin
    - Toggle: Admin → System emails (always on for admin)

36. Low Ticket Inventory Alert (Organizer)
    - Trigger: Ticket inventory falls below threshold
    - Recipient: Organizer
    - Toggle: Admin → Organizer emails

37. Event Sales Milestone (Organizer)
    - Trigger: Event reaches sales milestone (e.g., 100, 500, 1000 tickets)
    - Recipient: Organizer
    - Toggle: Admin → Organizer emails

#### 4.1.2 Template Structure

Each email template must include:
- **Header Section**
  - Site logo (automatically included)
  - Site name/branding

- **Body Section**
  - Dynamic content based on template type
  - Support for HTML formatting
  - Responsive design (mobile-friendly)

- **Footer Section**
  - Company information
  - Unsubscribe link (where applicable)
  - Social media links (optional)
  - Contact information

#### 4.1.3 Template Variables

All templates should support dynamic variables:

**User Variables:**
- `{{user_name}}` - Full name of the user
- `{{user_email}}` - User's email address
- `{{user_phone}}` - User's phone number

**Organizer Variables:**
- `{{organizer_name}}` - Organizer name/business name
- `{{organizer_email}}` - Organizer email

**Event Variables:**
- `{{event_title}}` - Event title
- `{{event_description}}` - Event description (short)
- `{{event_date}}` - Event date/time
- `{{event_location}}` - Event venue/location
- `{{event_image}}` - Event featured image URL

**Order/Ticket Variables:**
- `{{order_number}}` - Order reference number
- `{{order_date}}` - Order date
- `{{order_total}}` - Order total amount
- `{{ticket_number}}` - Ticket number
- `{{ticket_qr_code}}` - QR code image URL
- `{{ticket_type}}` - Ticket type name
- `{{ticket_quantity}}` - Number of tickets

**Payment Variables:**
- `{{payment_amount}}` - Payment amount
- `{{payment_method}}` - Payment method used
- `{{payment_status}}` - Payment status
- `{{transaction_id}}` - Transaction reference

**System Variables:**
- `{{platform_name}}` - Platform/site name
- `{{platform_url}}` - Platform URL
- `{{site_logo}}` - Site logo URL
- `{{verification_link}}` - Email verification link
- `{{reset_link}}` - Password reset link
- `{{unsubscribe_link}}` - Unsubscribe link
- `{{support_email}}` - Support email address
- `{{support_phone}}` - Support phone number

**Action/Status Variables:**
- `{{reason}}` - Reason for rejection/suspension/etc.
- `{{refund_amount}}` - Refund amount
- `{{payout_amount}}` - Payout amount
- `{{payout_reference}}` - Payout reference number

### 4.2 Admin Interface

#### 4.2.1 Navigation Structure

**Location:** Admin Panel → Settings → Email Templates

**Menu Structure:**
```
Admin Panel
└── Settings
    ├── General
    ├── Email Templates  ← NEW
    │   ├── All Templates
    │   ├── By Category
    │   │   ├── Authentication
    │   │   ├── Organizer
    │   │   ├── Events
    │   │   ├── Orders & Tickets
    │   │   ├── Payments
    │   │   ├── Payouts
    │   │   └── System Notifications
    │   ├── Email Controls
    │   │   ├── Customer Email Settings
    │   │   └── Organizer Email Settings
    │   └── Email Settings
    │       ├── Default Sender
    │       ├── Footer Content
    │       └── Branding
    └── [Other Settings...]
```

#### 4.2.2 Template List Page

**Route:** `/admin/settings/email-templates`

**Features:**
- List all email templates in a table
- Columns:
  - Template Name
  - Category
  - Recipient Role (Customer/Organizer/Admin)
  - Status (Enabled/Disabled)
  - Last Modified
  - Actions (Edit, Preview, Test, Toggle)
- Search/filter functionality:
  - Search by template name
  - Filter by category
  - Filter by recipient role
  - Filter by status (enabled/disabled)
- Bulk actions:
  - Enable selected templates
  - Disable selected templates

#### 4.2.3 Template Editor Page

**Route:** `/admin/settings/email-templates/{template}/edit`

**Features:**
1. **Template Information Section**
   - Template Name (read-only or editable)
   - Template Slug (read-only, system identifier)
   - Category (read-only)
   - Recipient Role (read-only)

2. **Email Settings**
   - Subject Line (with variable preview)
   - Enable/Disable toggle for this template
   - Preview button (opens preview modal)
   - Send test email button

3. **Content Editor**
   - WYSIWYG editor (TinyMCE or similar)
   - HTML source code view
   - Variable insertion tool/button
   - Live preview pane (optional)
   
4. **Template Content Sections**
   - Header (with logo placement indicator)
   - Body Content
   - Footer (customizable)
   
5. **Variable Helper**
   - List of available variables for this template
   - Click to insert into content
   - Variable description/usage hints

6. **Actions**
   - Save Template
   - Save & Preview
   - Save & Send Test
   - Reset to Default
   - Cancel

#### 4.2.4 Preview Functionality

**Modal/Page:** Preview Email Template

**Features:**
- Render email template with sample data
- Show both desktop and mobile preview
- Display actual email rendering (HTML)
- Show subject line preview
- Include sample variables populated
- Option to refresh preview after changes

**Sample Data:**
- Use realistic but fake data (e.g., "John Doe", "Sample Event", etc.)
- Show logo if configured
- Display all variables with sample values

#### 4.2.5 Test Email Functionality

**Modal/Form:** Send Test Email

**Features:**
1. Test Email Form:
   - Recipient Email Address (required)
   - Use sample data toggle (checkbox)
   - Custom variables (optional, override sample data)
   
2. Send Options:
   - Send button
   - Cancel button
   
3. Confirmation:
   - Success message
   - Error message if failed
   - Email sent notification

**Sample Data Mode:**
- Populate all variables with sample data
- Use actual site logo
- Use actual platform name

**Custom Data Mode:**
- Allow admin to input custom values for variables
- Use custom values in test email

#### 4.2.6 Role-Based Email Controls

**Route:** `/admin/settings/email-templates/controls`

**Page Structure:**

**A. Customer Email Settings Section**
- Title: "Customer Email Notifications"
- Description: "Enable or disable email notifications sent to customers"
- List of all customer-related templates with toggle switches
- Grouped by category:
  - Authentication (Registration, Verification, Password Reset, etc.)
  - Orders & Tickets (Order Confirmation, Ticket Purchase, etc.)
  - Events (Event Reminder, Event Cancelled, etc.)
  - Payments (Payment Successful, Refunds, etc.)

**B. Organizer Email Settings Section**
- Title: "Organizer Email Notifications"
- Description: "Enable or disable email notifications sent to organizers"
- List of all organizer-related templates with toggle switches
- Grouped by category:
  - Account (Approval, Rejection, Verification)
  - Events (Submitted, Approved, Rejected, etc.)
  - Payouts (Requested, Processing, Completed, Failed)
  - System (Low Inventory, Sales Milestone)

**C. Bulk Actions**
- "Enable All Customer Emails" button
- "Disable All Customer Emails" button
- "Enable All Organizer Emails" button
- "Disable All Organizer Emails" button
- "Save Changes" button

**Toggle Behavior:**
- Each template has an on/off switch
- Toggle state is saved immediately or on "Save Changes"
- Disabled templates will NOT send emails, even if triggered
- Visual indication of enabled/disabled state

#### 4.2.7 Email Settings Page

**Route:** `/admin/settings/email-templates/settings`

**Sections:**

1. **Default Sender Information**
   - From Name (default: platform name)
   - From Email (default: system email)
   - Reply-To Email
   
2. **Site Logo**
   - Upload logo image
   - Logo URL input
   - Logo preview
   - Logo dimensions/guidelines
   - Logo will appear in all email templates

3. **Email Footer**
   - Company Name
   - Company Address
   - Support Email
   - Support Phone
   - Website URL
   - Footer HTML (optional, custom footer)

4. **Branding**
   - Primary Color (for email accents)
   - Secondary Color
   - Font Family (default: system fonts)

5. **Advanced Settings**
   - Email Header HTML (optional)
   - Email Footer HTML (optional)
   - CSS Styles (for email styling)

### 4.3 Database Schema

#### 4.3.1 Email Templates Table

```sql
email_templates
- id (primary key)
- slug (unique, system identifier, e.g., 'user_registration_welcome')
- name (human-readable name, e.g., 'User Registration Welcome')
- category (enum: authentication, organizer, events, orders_tickets, payments, payouts, system)
- recipient_role (enum: customer, organizer, admin)
- subject (subject line with variables)
- html_content (HTML version of email)
- plain_text_content (plain text version)
- description (what this template is used for)
- variables_available (JSON array of available variables)
- is_active (boolean, default: true)
- is_system (boolean, default: false - system templates cannot be deleted)
- default_template (JSON, original/default content)
- created_at
- updated_at
```

#### 4.3.2 Email Settings Table

```sql
email_settings
- id (primary key)
- setting_key (unique, e.g., 'logo_url', 'from_name')
- setting_value (text/JSON)
- setting_type (enum: text, json, file)
- group (enum: sender, branding, footer)
- created_at
- updated_at
```

**Or use existing `platform_settings` table with keys:**
- `email_logo_url`
- `email_from_name`
- `email_from_address`
- `email_reply_to`
- `email_footer_html`
- `email_primary_color`
- etc.

#### 4.3.3 Email Controls Table

```sql
email_controls
- id (primary key)
- template_slug (foreign key to email_templates)
- role (enum: customer, organizer)
- is_enabled (boolean, default: true)
- created_at
- updated_at
- unique constraint: (template_slug, role)
```

### 4.4 Technical Requirements

#### 4.4.1 Logo Integration

- Logo must be accessible via URL
- Logo will be included in email header section
- Logo size recommendations: max 200px width, optimized for email
- Support for PNG, JPG, SVG (convert to PNG for email)
- Fallback: Site name as text if logo not available

#### 4.4.2 Template Rendering

- All templates use a base email layout
- Base layout includes:
  - Header with logo
  - Content area (template-specific)
  - Footer with company info
- Templates are rendered with variables replaced
- HTML emails are responsive (mobile-friendly)
- Plain text versions generated automatically or manually

#### 4.4.3 Email Sending Logic

Before sending any email:
1. Check if template exists
2. Check if template is enabled (is_active = true)
3. Check if email is enabled for recipient role (email_controls table)
4. If all checks pass, render template and send email
5. If any check fails, log but don't send (or send default system email if critical)

#### 4.4.4 Editor Requirements

- WYSIWYG editor with HTML source view
- Variable insertion tool
- Image upload/insertion
- Formatting tools (bold, italic, lists, links, etc.)
- Table support (for structured content)
- Preview in editor
- Save drafts functionality

**Recommended:** TinyMCE, CKEditor, or similar

### 4.5 User Experience Requirements

#### 4.5.1 Admin Workflow

1. **Accessing Email Templates:**
   - Navigate to Settings → Email Templates
   - View list of all templates
   - Search/filter to find specific template

2. **Editing a Template:**
   - Click "Edit" on desired template
   - Modify subject line and content
   - Use variable helper to insert variables
   - Preview template with sample data
   - Save changes

3. **Testing a Template:**
   - Click "Send Test Email" button
   - Enter recipient email address
   - Choose sample data or custom data
   - Send test email
   - Verify email received

4. **Controlling Email Notifications:**
   - Navigate to Email Controls page
   - Toggle individual templates on/off
   - Use bulk actions to enable/disable all
   - Save changes

5. **Configuring Email Settings:**
   - Navigate to Email Settings page
   - Upload/configure logo
   - Set default sender information
   - Customize footer
   - Save settings

#### 4.5.2 Visual Design

- Clean, modern admin interface
- Clear categorization of templates
- Visual indicators for enabled/disabled status
- Color coding by category
- Intuitive icons for actions
- Responsive design (works on tablets)

### 4.6 Implementation Phases

#### Phase 1: Core Infrastructure
- Database tables creation
- Base email layout/template
- Logo integration system
- Template model and relationships

#### Phase 2: Admin Interface - Template Management
- Template list page
- Template editor page
- Basic CRUD operations
- Variable system implementation

#### Phase 3: Preview & Test Functionality
- Preview modal/page
- Test email sending
- Sample data generation

#### Phase 4: Role-Based Controls
- Email controls page
- Toggle functionality
- Bulk actions
- Integration with email sending logic

#### Phase 5: Email Settings
- Settings page
- Logo upload/management
- Footer customization
- Sender information

#### Phase 6: Template Content
- Create all 37 email templates
- Default content for each template
- Variable mapping

#### Phase 7: Integration
- Update existing email sending code
- Replace hardcoded emails with template system
- Testing all email triggers

#### Phase 8: Polish & Documentation
- UI/UX refinements
- Admin documentation
- User guide

### 4.7 Success Criteria

1. ✅ All email templates are editable through admin interface
2. ✅ Site logo appears in all email templates
3. ✅ Admin can enable/disable emails per role (Customer/Organizer)
4. ✅ Preview functionality works for all templates
5. ✅ Test email sending works reliably
6. ✅ All existing email functionality continues to work
7. ✅ New email templates can be added easily
8. ✅ Templates support all required variables
9. ✅ Responsive email design (mobile-friendly)
10. ✅ System is maintainable and scalable

### 4.8 Future Enhancements (Out of Scope)

- Email analytics (open rates, click rates)
- A/B testing for email templates
- Email scheduling
- Email automation workflows
- Multi-language email templates
- Email template versioning/history
- User-level email preferences (customers can opt-out)

---

## 5. Approval & Sign-off

**Document Status:** Draft - Awaiting Approval

**Prepared By:** AI Assistant

**Date:** [Current Date]

**Next Steps:**
1. Review PRD with stakeholders
2. Get approval for requirements
3. Begin Phase 1 implementation
4. Regular progress updates

---

**Please review this PRD and let me know:**
1. Are all requirements correct?
2. Any missing features or templates?
3. Any changes needed to the structure or flow?
4. Ready to proceed with implementation?