# Epic 8: Email Notification System

## Epic Goal

Implement a comprehensive email notification system with professional templates, bilingual support, and reliable delivery for all platform communications.

## Epic Description

### Business Context

Email is the primary communication channel. Clients receive mandatory notifications (no opt-out) for account creation, booking updates, reminders, and timeline updates. Admin receives notifications for new bookings and system events.

### Technical Context

- **Sender:** no-reply@libra.ps
- **Sender Name:** Libra Law Firm / مكتب ليبرا للمحاماة
- **SMTP:** Configured via .env
- **Delivery:** All mandatory (no opt-out for clients)
- **Templates:** Professional with branding

### Success Criteria

- [ ] Professional email templates with branding
- [ ] Bilingual emails (based on recipient preference)
- [ ] All 9+ notification types implemented
- [ ] Calendar file attachments
- [ ] Queued delivery for performance
- [ ] Plain text fallback
- [ ] Consistent branding across all emails

---

## Stories

### Story 8.1: Email Infrastructure Setup

**Description:** Configure email sending infrastructure and base template.

**Acceptance Criteria:**
- [ ] SMTP configuration via .env:
  - MAIL_MAILER
  - MAIL_HOST
  - MAIL_PORT
  - MAIL_USERNAME
  - MAIL_PASSWORD
  - MAIL_ENCRYPTION
  - MAIL_FROM_ADDRESS (no-reply@libra.ps)
  - MAIL_FROM_NAME
- [ ] Base email template with:
  - Libra logo header
  - Navy blue (#0A1F44) and gold (#D4AF37) colors
  - Professional typography
  - Footer with firm contact info
  - Mobile-responsive layout
- [ ] Plain text fallback generation
- [ ] Queue configuration for async sending
- [ ] Email logging for debugging

**Technical Notes:**
- Use Laravel Mail with Mailable classes
- Create base Mailable with shared layout
- Configure queue connection

---

### Story 8.2: Welcome Email (Account Created)

**Description:** Email sent when admin creates a new client account.

**Acceptance Criteria:**
- [ ] Triggered on user creation
- [ ] **Content:**
  - Personalized greeting (name/company)
  - "Your account has been created"
  - Login credentials (email, password)
  - Login URL link
  - Brief platform introduction
  - Contact info for questions
- [ ] Language based on user's preferred_language
- [ ] Call-to-action button: "Login Now"
- [ ] Security note about changing password (N/A - admin only)

**Technical Notes:**
- Mailable: WelcomeEmail
- Trigger: User created event
- Queue for performance

---

### Story 8.3: Booking Submitted Confirmation

**Description:** Email to client confirming their booking request was submitted.

**Acceptance Criteria:**
- [ ] Triggered on booking submission
- [ ] **Content:**
  - "Your consultation request has been submitted"
  - Requested date and time
  - Problem summary preview
  - "Pending Review" status note
  - Expected response timeframe (general)
- [ ] Language based on client preference
- [ ] No action required message

**Technical Notes:**
- Mailable: BookingSubmittedEmail
- Trigger: Consultation created with status 'pending'

---

### Story 8.4: Booking Approved Email

**Description:** Email to client when admin approves their booking.

**Acceptance Criteria:**
- [ ] Triggered on booking approval
- [ ] **Content:**
  - "Your consultation has been approved"
  - Confirmed date and time
  - Duration (45 minutes)
  - Consultation type (free/paid)
  - If paid: amount and payment instructions
  - Calendar file (.ics) attached
  - "Add to Calendar" button/link
  - Location/contact information
- [ ] Language based on client preference
- [ ] Professional confirmation tone

**Technical Notes:**
- Mailable: BookingApprovedEmail
- Attach .ics file from Epic 3
- Trigger: Consultation status changed to 'approved'

---

### Story 8.5: Booking Rejected Email

**Description:** Email to client when admin rejects their booking.

**Acceptance Criteria:**
- [ ] Triggered on booking rejection
- [ ] **Content:**
  - "Your consultation request could not be approved"
  - Original requested date and time
  - Rejection reason (if provided by admin)
  - Invitation to request new consultation
  - Contact info for questions
- [ ] Empathetic, professional tone
- [ ] Language based on client preference

**Technical Notes:**
- Mailable: BookingRejectedEmail
- Optional reason field from admin
- Trigger: Consultation status changed to 'rejected'

---

### Story 8.6: Consultation Reminder (24 Hours)

**Description:** Reminder email sent 24 hours before scheduled consultation.

**Acceptance Criteria:**
- [ ] Scheduled job runs daily
- [ ] Find consultations 24 hours away
- [ ] **Content:**
  - "Reminder: Your consultation is tomorrow"
  - Date and time
  - Consultation type
  - Payment reminder (if paid and not received)
  - Calendar file link
  - Any preparation notes
- [ ] Skip cancelled/no-show consultations
- [ ] Language based on client preference

**Technical Notes:**
- Scheduled command: php artisan reminders:send-24h
- Run via Laravel scheduler
- Mailable: ConsultationReminder24Email

---

### Story 8.7: Consultation Reminder (2 Hours)

**Description:** Reminder email sent 2 hours before scheduled consultation.

**Acceptance Criteria:**
- [ ] Scheduled job runs hourly
- [ ] Find consultations 2 hours away
- [ ] **Content:**
  - "Your consultation is in 2 hours"
  - Date and time
  - Final payment reminder (if applicable)
  - Contact info for last-minute issues
- [ ] Skip cancelled/no-show consultations
- [ ] Language based on client preference

**Technical Notes:**
- Scheduled command: php artisan reminders:send-2h
- More frequent checks for accuracy
- Mailable: ConsultationReminder2hEmail

---

### Story 8.8: Timeline Update Notification

**Description:** Email to client when admin adds update to their timeline.

**Acceptance Criteria:**
- [ ] Triggered on timeline update creation
- [ ] **Content:**
  - "Update on your case: [Case Name]"
  - Case reference number
  - Update content (full or summary)
  - Date of update
  - "View Timeline" button/link
- [ ] Language based on client preference
- [ ] Professional, informative tone

**Technical Notes:**
- Mailable: TimelineUpdateEmail
- Trigger: TimelineUpdate created event
- Link to client dashboard timeline view

---

### Story 8.9: Admin Notification - New Booking

**Description:** Email to admin when client submits new booking request.

**Acceptance Criteria:**
- [ ] Triggered on booking submission
- [ ] Sent to admin email
- [ ] **Content:**
  - "New Consultation Request"
  - Client name (individual or company)
  - Requested date and time
  - Problem summary (full)
  - Client contact info
  - "Review Request" button/link
- [ ] Admin language preference (or default)
- [ ] Priority indicator in subject line

**Technical Notes:**
- Mailable: NewBookingAdminEmail
- Send to configured admin email
- Include direct link to booking management

---

### Story 8.10: Admin Notification - System Events

**Description:** Critical system notifications to admin.

**Acceptance Criteria:**
- [ ] Email failures notification
- [ ] Scheduled job failures notification
- [ ] Critical errors summary
- [ ] **Content:**
  - Event type and description
  - Timestamp
  - Relevant details
  - Recommended action (if any)
- [ ] Sent immediately (not queued)
- [ ] Clear subject line indicating urgency

**Technical Notes:**
- Use Laravel exception handler
- Monitor queues and scheduler
- Consider separate notification channel

---

## Dependencies

| Epic | Dependency |
|------|------------|
| Epic 1 | Base application, user preferences |
| Epic 2 | User creation (welcome email) |
| Epic 3 | Booking events, calendar files |
| Epic 4 | Timeline updates |

## Risks & Mitigations

| Risk | Impact | Mitigation |
|------|--------|------------|
| Email delivery failures | High | Queue retry, logging, admin alerts |
| SMTP configuration issues | High | Test email feature, validation |
| Spam filtering | Medium | Proper SPF/DKIM, professional content |
| Timezone issues in reminders | Medium | Store and display in consistent timezone |

## Definition of Done

- [ ] All stories completed with acceptance criteria met
- [ ] All 9+ email types implemented
- [ ] Emails render correctly (HTML and plain text)
- [ ] Bilingual emails working
- [ ] Branding consistent across all emails
- [ ] Queue processing reliable
- [ ] Reminder jobs scheduled and tested
- [ ] Calendar attachments working
- [ ] Admin notifications delivered
- [ ] Code formatted with Pint