# Email-to-Case V2 (Tenant-Specific) - TODO Status

**Last Updated:** February 7, 2026  
**Status:** ⏳ PENDING - Not started in this session

---

## 📋 OUTSTANDING TODOS (18 Items)

### Implementation Tasks (10 items) - Status: PENDING

1. **Design tenant-specific email address scheme** (ID: email-to-case-1)
   - Status: ⏳ PENDING
   - Example: `tenant-{short_id}@arvelobuilt.com` or `{tenant_slug}@crm.arvelobuilt.com`
   
2. **Add email_to_case_address column to tenants table** (ID: email-to-case-2)
   - Status: ⏳ PENDING
   - Store unique BCC address per tenant

3. **Create migration script** (ID: email-to-case-3)
   - Status: ⏳ PENDING
   - Generate unique BCC addresses for existing tenants

4. **Update EmailToCaseService** (ID: email-to-case-4)
   - Status: ⏳ PENDING
   - Extract tenant from email address (not from lead lookup)

5. **Update lead matching** (ID: email-to-case-5)
   - Status: ⏳ PENDING
   - ONLY search within identified tenant (tenant_id filter)

6. **Add notification system for 'lead not found'** (ID: email-to-case-6)
   - Status: ⏳ PENDING
   - Email tenant admins with unmatched email details

7. **Update lead-detail.php** (ID: email-to-case-7)
   - Status: ⏳ PENDING
   - Show tenant-specific BCC address with copy button

8. **Update admin settings** (ID: email-to-case-8)
   - Status: ⏳ PENDING
   - Display/manage tenant's Email-to-Case address

9. **Configure MXRoute wildcard forwarding** (ID: email-to-case-9)
   - Status: ⏳ PENDING
   - Setup for tenant-*.arvelobuilt.com or *.crm.arvelobuilt.com

10. **Update documentation** (ID: email-to-case-10)
    - Status: ⏳ PENDING
    - EMAIL_TO_CASE_IMPLEMENTATION.md with new tenant-specific approach

### Testing Tasks (8 items) - Status: PENDING

11. **TEST: Verify unique BCC address visible** (ID: test-email-to-case-1)
    - Status: ⏳ PENDING
    - Each tenant has unique BCC address in lead detail page

12. **TEST: Tenant A email tracking** (ID: test-email-to-case-2)
    - Status: ⏳ PENDING
    - Send email TO lead in Tenant A, BCC Tenant A's address
    - Verify activity appears on Tenant A lead only

13. **TEST: Tenant B email tracking** (ID: test-email-to-case-3)
    - Status: ⏳ PENDING
    - Send email TO lead in Tenant B, BCC Tenant B's address
    - Verify activity appears on Tenant B lead only

14. **TEST: Cross-tenant isolation** (ID: test-email-to-case-4)
    - Status: ⏳ PENDING
    - BCC Tenant A's address with Tenant B's lead email
    - Verify NO activity created on Tenant B

15. **TEST: Lead not found notification** (ID: test-email-to-case-5)
    - Status: ⏳ PENDING
    - BCC tenant address with unknown lead email
    - Verify tenant admin receives notification email

16. **TEST: Invalid tenant address** (ID: test-email-to-case-6)
    - Status: ⏳ PENDING
    - BCC non-existent tenant address
    - Verify graceful error handling and logging

17. **TEST: Copy button functionality** (ID: test-email-to-case-7)
    - Status: ⏳ PENDING
    - Click copy button on BCC address in lead detail page
    - Verify copied to clipboard

18. **TEST: Admin panel display** (ID: test-email-to-case-8)
    - Status: ⏳ PENDING
    - Check admin panel shows tenant's unique Email-to-Case address
    - Verify setup instructions displayed

---

## 🎯 PRIORITY & TIMELINE

### Priority Level
**MEDIUM** - Feature enhancement, not critical bug

### Estimated Effort
- Implementation: ~4-6 hours
- Testing: ~2-3 hours
- Documentation: ~1 hour
- **Total:** ~7-10 hours

### Dependencies
- MXRoute configuration access
- DNS management (if using subdomains)
- Email testing capability
- Tenant admin email addresses

### Risks
- **MXRoute Configuration:** May need provider support for wildcard routing
- **DNS Changes:** Requires propagation time (24-48 hours)
- **Email Deliverability:** Must not impact existing Parsley parser
- **Tenant Migration:** Existing tenants need BCC addresses generated

---

## 📖 CONTEXT & BACKGROUND

### Current System (Email-to-Case V1)
- **Single BCC address:** All tenants use same BCC (`arv@arvelobuilt.com`)
- **Security Flaw:** Cross-tenant data exposure risk
- **Lead Matching:** Searches ALL tenants for matching lead
- **No Notifications:** Unknown leads fail silently

### Desired System (Email-to-Case V2)
- **Unique BCC per tenant:** e.g., `tenant-abc123@arvelobuilt.com`
- **Tenant Isolation:** Extract tenant from BCC address before lead lookup
- **Scoped Matching:** Only search within identified tenant
- **Tenant Notifications:** Alert admins when lead not found in their tenant

### Benefits
✅ **Security:** Eliminates cross-tenant data exposure  
✅ **Scalability:** Works with 1,000+ tenants  
✅ **Reliability:** Failed emails notify correct tenant  
✅ **Compliance:** Better data isolation for SOC 2/GDPR  

### Similar to Salesforce
This follows Salesforce Email-to-Case design pattern where each org has unique email addresses.

---

## 🚧 WORK COMPLETED IN OTHER SESSIONS

### Previous Work (from earlier deployment)
- ✅ Created EmailToCaseService.php class
- ✅ Created unmatched_emails table
- ✅ Basic email parsing infrastructure
- ✅ Tenant context management

### Recent Session (Feb 7, 2026)
**Focus:** Bug fixes and improvements (NOT Email-to-Case)
- ✅ Fixed Parsley forwarded email parsing
- ✅ Fixed duplicate detection
- ✅ Fixed activity timeline UI
- ✅ Fixed leads list sorting

**Email-to-Case work:** Not touched in this session

---

## 📋 NEXT STEPS (When Ready to Resume)

### Step 1: Planning & Design
1. Finalize email address format (recommend: `tenant-{uuid}@arvelobuilt.com`)
2. Review MXRoute capabilities for wildcard forwarding
3. Design database schema changes
4. Plan migration strategy for existing tenants

### Step 2: Implementation
1. Add `email_to_case_address` column to tenants
2. Create generation script for unique addresses
3. Refactor EmailToCaseService for tenant extraction
4. Update lead-detail.php UI
5. Update admin.php UI
6. Configure MXRoute

### Step 3: Testing
1. Test with multiple tenants
2. Verify cross-tenant isolation
3. Test notification system
4. Load testing with high volume

### Step 4: Deployment
1. Run database migration
2. Generate addresses for existing tenants
3. Deploy code changes
4. Configure MXRoute wildcards
5. Update documentation
6. Train users

---

## 💡 RECOMMENDATIONS

### Before Starting
- [ ] Confirm MXRoute supports wildcard forwarding
- [ ] Get DNS access for subdomain configuration (if needed)
- [ ] Review tenant list and contact info
- [ ] Set up email testing environment
- [ ] Create rollback plan

### During Development
- [ ] Keep V1 system running during migration
- [ ] Test with 2-3 pilot tenants first
- [ ] Monitor email delivery rates
- [ ] Log all email processing for debugging

### After Deployment
- [ ] Monitor for 48 hours
- [ ] Collect user feedback
- [ ] Measure success metrics
- [ ] Update training materials

---

## 📞 STAKEHOLDER COMMUNICATION

**To User:** Email-to-Case V2 is a planned enhancement that will improve security and scalability. It's not urgent and can be scheduled when ready. The recent bug fixes (Parsley, duplicates, sorting) were prioritized first as they had immediate user impact.

**Benefits When Implemented:**
- Better data security (tenant isolation)
- Clearer error messages (tenant-specific notifications)
- Salesforce-style email tracking
- Easier debugging (unique addresses per tenant)

**No Action Required:** System works correctly with current Email-to-Case V1 for now.

---

**Status:** 📊 18 TODOs remain for Email-to-Case V2 implementation (all pending)