# Email Notification Strategy - Quick Reference

## 🎯 **9 Email Scenarios (Priority Order)**

### **✅ CRITICAL (Always Send if Admin Enabled)**
1. **TAT Breached (100%)** → Approver + Management
2. **Request Rejected** → Initiator

### **✅ HIGH PRIORITY (Check Preferences)**
3. **Request Created** → Initiator
4. **Approval Request** → Approver (action required)
5. **Request Approved** → Initiator
6. **TAT Reminder (75%)** → Approver
7. **Workflow Resumed** → Approver + Initiator

### **✅ MEDIUM PRIORITY (Check Preferences)**
8. **TAT Reminder (50%)** → Approver

### **✅ LOW PRIORITY (Check Preferences)**
9. **Request Closed** → All Participants

---

## 🔐 **Preference Control Flow**

### **Before Sending ANY Email:**

```typescript
import { shouldSendEmail, EmailNotificationType } from '@/emailtemplates/emailPreferences.helper';

// Check preferences
const canSendEmail = await shouldSendEmail(
  userId,
  EmailNotificationType.APPROVAL_REQUEST
);

if (!canSendEmail) {
  logger.info(`Email skipped for user ${userId} due to preferences`);
  return; // Don't send email
}

// Proceed with email
await emailService.sendEmail(...);
```

### **Preference Logic:**

```
Admin Enabled? ──NO──> ❌ Stop (Don't send)
      │
     YES
      │
      ▼
User Enabled? ──NO──> ❌ Stop (Don't send)
      │
     YES
      │
      ▼
   ✅ Send Email
```

### **Critical Email Override:**

```typescript
// For CRITICAL emails (Rejection, TAT Breach)
const canSend = await shouldSendEmailWithOverride(
  userId,
  EmailNotificationType.REQUEST_REJECTED
);
// This checks admin only, ignores user preference
```

---

## 📊 **TAT Email Schedule (3 Reminders)**

| TAT Progress | Template | Priority | Subject | When |
|--------------|----------|----------|---------|------|
| **50%** | TATReminder | Medium | TAT Reminder - Early Warning | Half TAT elapsed |
| **75%** | TATReminder | High | TAT Reminder - Action Needed | 3/4 TAT elapsed |
| **100%** | TATBreached | Critical | TAT BREACHED - Urgent | Deadline passed |

### **TAT Reminder Template Customization:**

```typescript
// 50% Reminder
await emailNotificationService.sendTATReminder(
  workflow,
  approver,
  {
    threshold: 50,
    timeRemaining: '12 hours',
    urgency: 'early-warning'
  }
);

// 75% Reminder
await emailNotificationService.sendTATReminder(
  workflow,
  approver,
  {
    threshold: 75,
    timeRemaining: '6 hours',
    urgency: 'urgent'
  }
);

// 100% Breach
await emailNotificationService.sendTATBreached(
  workflow,
  approver,
  {
    timeOverdue: '2 hours overdue',
    notifyManagement: true
  }
);
```

---

## 🚫 **Never Send Email For:**

### **In-App Only (Real-Time Collaboration):**

| Notification Type | Why In-App Only | Frequency |
|-------------------|-----------------|-----------|
| @Mentions | Real-time chat | High (50-200/day) |
| Comments | Active discussion | High (100-300/day) |
| Documents Added | Minor update | Medium (20-50/day) |
| Status Changes | Internal updates | Medium (30-80/day) |
| AI Generated | Background process | Low (10-20/day) |
| Summary Generated | Automatic | Low (10-20/day) |

**Reason:** These would flood inboxes and cause email fatigue!

---

## 💾 **Important: Activity Logs**

### **ALWAYS Capture Activities:**

```typescript
// Even if email/notification disabled, ALWAYS log activity
await activityService.log({
  requestId,
  type: 'approval',
  user: { userId, name },
  timestamp: new Date().toISOString(),
  action: 'Request approved',
  details: 'Approved by John Doe'
});

// This is independent of email/notification preferences
// Activity logs are for audit trail and compliance
```

**Activities Logged Regardless of Preferences:**
- ✅ Request created
- ✅ Assignments
- ✅ Approvals
- ✅ Rejections
- ✅ TAT events (50%, 75%, 100%)
- ✅ Pauses/Resumes
- ✅ Comments
- ✅ Documents
- ✅ Status changes

---

## 🔧 **Implementation Checklist**

### **Before Starting:**
- [ ] Create `emailPreferences.helper.ts` ✅ Done
- [ ] Add system config entries for email controls
- [ ] Update user preferences schema
- [ ] Test preference checking logic

### **For Each Email Type:**
1. [ ] Check admin preference
2. [ ] Check user preference
3. [ ] Send email only if both enabled
4. [ ] Log activity regardless
5. [ ] Handle errors gracefully
6. [ ] Track metrics (sent/failed/skipped)

### **Critical Emails (Special Handling):**
- [ ] Request Rejected - Override user preference
- [ ] TAT Breached - Override user preference
- [ ] Still respect admin disable

---

## 📋 **User Preference UI (Frontend)**

### **Admin Settings Page:**

```
Email Notifications (Global Control)
├── [✓] Enable Email Notifications
│
├── Request Lifecycle
│   ├── [✓] Request Created
│   ├── [✓] Approval Requests
│   ├── [✓] Request Approved
│   └── [✓] Request Rejected (Critical - Recommended)
│
├── TAT Alerts
│   ├── [✓] TAT 50% Reminder
│   ├── [✓] TAT 75% Reminder
│   └── [✓] TAT Breached (Critical - Recommended)
│
└── Workflow Control
    ├── [✓] Workflow Resumed
    └── [✓] Request Closed
```

### **User Preferences Page:**

```
My Email Preferences
├── [✓] Receive Email Notifications
│
├── Request Updates
│   ├── [✓] When my request is created
│   ├── [✓] When assigned to approve
│   ├── [✓] When my request is approved
│   ├── [⚠] When my request is rejected (Cannot disable - Critical)
│
├── TAT Alerts
│   ├── [✓] TAT 50% reminder
│   ├── [✓] TAT 75% reminder
│   └── [⚠] TAT breached (Cannot disable - Critical)
│
└── Other
    ├── [✓] Workflow resumed
    └── [ ] Request closed (Optional)
```

**Note:** Critical emails cannot be disabled by users!

---

## 📊 **Email Volume with Preferences**

### **Without Preferences (All Emails):**
- ~75-205 emails/day

### **With Smart Defaults:**
- Users who want all: ~75-205 emails/day
- Users who opt for critical only: ~10-20 emails/day
- Average user: ~30-50 emails/day

### **Email Savings:**
- @Mentions: 50-200/day saved ✅
- Comments: 100-300/day saved ✅
- Documents: 20-50/day saved ✅
- Status changes: 30-80/day saved ✅

**Total saved: 200-630 potential emails/day!**

---

## ✅ **Summary**

### **Email Strategy:**
1. ✅ **9 email scenarios** (high-impact only)
2. ✅ **TAT reminders at 50%, 75%, 100%**
3. ✅ **Admin-level control** (can disable globally)
4. ✅ **User-level control** (individual preferences)
5. ✅ **Critical override** (rejection, breach always sent)
6. ✅ **Activity logs** always captured
7. ✅ **In-app only** for collaboration (@mentions, comments)

### **Implementation Order:**
1. Phase 0: Preference system ← **START HERE**
2. Phase 1: Email service
3. Phase 2: Critical emails (rejection, breach)
4. Phase 3: High priority emails
5. Phase 4: Medium/low priority emails
6. Phase 5: User preference UI

---

**Ready to implement Phase 0 (Preference System)?** 🚀