# Email Tracking Quick Reference

## ✅ Latest Updates (Jan 15, 2026)

### Key Fixes Applied to EmailTrigger.php
- ✅ Removed hardcoded user ID (113840) - now uses actual buyer from lead
- ✅ Cleaned all debug code (dd statements, comments)
- ✅ Fixed redundant database queries
- ✅ Removed duplicate 'email' key in mapping
- ✅ Integrated with EmailTrackingService properly
- ✅ Removed 20+ lines of dead/commented code
- ✅ Fixed return type mismatches

## 🚀 Quick Start Testing

### 1. Generate Test Email
```
http://yourdomain.com/test-email-tracking
```

### 2. Tracking URLs (5 methods)
```
Logo:     http://yourdomain.com/track/logo/{email_id}    (Primary - most reliable)
Footer:   http://yourdomain.com/track/footer/{email_id}  (Backup)
Pixel:    http://yourdomain.com/track/open/{email_id}    (Fallback - may be blocked)
Click:    http://yourdomain.com/track/click/{email_id}   (Redirects to quotation)
Download: http://yourdomain.com/track/download/{email_id} (Redirects to PDF)
```

---

## 📊 What Gets Tracked

| Event | Tracked Data | Database Table |
|-------|--------------|----------------|
| **Email Open** | IP, User Agent, Timestamp | `auto_quote_email_events` |
| **Link Click** | IP, User Agent, Timestamp, Referrer | `auto_quote_email_events` |
| **File Download** | IP, User Agent, Timestamp | `auto_quote_email_events` |

---

## 🗄️ Database Schema

### auto_quote_emails
```
id, quotation_number, recipient_email
open_count, first_opened_at, last_opened_at
click_count, first_clicked_at, last_clicked_at  
download_count, first_downloaded_at, last_downloaded_at
```

### auto_quote_email_events
```
id, auto_quote_email_id, event_type
ip_address, user_agent, referrer, created_at
```

---

## ✅ Testing Checklist

- [ ] Visit `/test-email-tracking` to create test email
- [ ] Click "Test Open Tracking" link
- [ ] Click "Test Click Tracking" link
- [ ] Click "Test Download Tracking" link
- [ ] Click "View Stats" to see results
- [ ] Verify counts incremented
- [ ] Check database records manually

---

## 🔍 Manual Verification

### Check Email Record
```sql
SELECT * FROM auto_quote_emails 
WHERE id = {email_id};
```

### Check Events
```sql
SELECT * FROM auto_quote_email_events 
WHERE auto_quote_email_id = {email_id}
ORDER BY created_at DESC;
```

### Check Summary Stats
```sql
SELECT 
  COUNT(*) as total_events,
  SUM(CASE WHEN event_type = 'open' THEN 1 ELSE 0 END) as opens,
  SUM(CASE WHEN event_type = 'click' THEN 1 ELSE 0 END) as clicks,
  SUM(CASE WHEN event_type = 'download' THEN 1 ELSE 0 END) as downloads
FROM auto_quote_email_events
WHERE auto_quote_email_id = {email_id};
```

---

## 🐛 Troubleshooting

| Problem | Solution |
|---------|----------|
| 404 on pixel | Create pixel: `cd public && echo "base64..." \| base64 -d > pixel.png` |
| No events recorded | Check logs: `tail -f storage/logs/laravel.log \| grep track` |
| Wrong namespace | Run: `composer dump-autoload` |
| Database error | Run migrations: `php artisan migrate` |

---

## 📈 How It Works

```
1. Email Sent
   ↓
2. Tracking pixel embedded: <img src="/track/open/123" />
   ↓
3. Links replaced: /track/click/123
   ↓
4. Buyer opens email → Pixel loads → trackOpen() → Database
   ↓
5. Buyer clicks link → trackClick() → Database → Redirect
```

---

## 🎯 Key Files

| File | Purpose |
|------|---------|
| `routes/web.php` | Tracking routes |
| `app/Services/AutoQuotation/Helpers/EmailTrigger.php` | Embeds tracking |
| `app/Service/AutoQuote/EmailTrackingService.php` | Records events |
| `public/pixel.png` | Tracking pixel (1x1 transparent) |

---

## 📚 Documentation

- **Technical Docs:** `EMAIL_TRACKING_TECHNICAL_DOCUMENTATION.md`
- **Testing Guide:** `EMAIL_TRACKING_TESTING_GUIDE.md`
- **This File:** `EMAIL_TRACKING_QUICK_REFERENCE.md`

---

## 🔒 Production Notes

### Before Going Live:

1. ✅ Test all tracking URLs
2. ✅ Verify pixel file exists
3. ✅ Check database indexes
4. ✅ Set up monitoring
5. ⚠️ **Remove** test routes:
   - `/test-email-tracking`
   - `/test-email-tracking/stats/{id}`
6. ✅ Add rate limiting
7. ✅ Set up alerts for errors
8. ✅ Review privacy policy

### Remove Test Routes (In web.php):
```php
// DELETE THESE LINES IN PRODUCTION:
Route::get('/test-email-tracking', ...);
Route::get('/test-email-tracking/stats/{id}', ...);
```

---

## 📞 Support

**Check Logs:**
```bash
tail -f storage/logs/laravel.log | grep track
```

**Test Pixel:**
```bash
curl -I http://yourdomain.com/track/open/1
```

**Database Check:**
```bash
php artisan tinker
>>> \App\Models\Crm\Quote\AutoQuoteEmail::latest()->first()
```

---

**Last Updated:** January 13, 2026