WooNooW/EMAIL_DEBUGGING_GUIDE.md

# Email Debugging Guide

## 🔍 Problem: Emails Not Sending

Action Scheduler shows "Complete" but no emails appear in Email Log plugin.

## 📋 Diagnostic Tools

### 1. Check Settings
```
Visit: /wp-content/plugins/woonoow/check-settings.php
```
This shows:
- Notification system mode
- Email channel status
- Event configuration
- Template configuration
- Hook registration status
- Action Scheduler stats
- Queued emails

### 2. Test Email Flow
```
Visit: /wp-content/plugins/woonoow/test-email-flow.php
```
Interactive dashboard with:
- System status
- Test buttons
- Queue viewer
- Action Scheduler monitor

### 3. Direct Email Test
```
Visit: /wp-content/plugins/woonoow/test-email-direct.php
```
Or via WP-CLI:
```bash
wp eval-file wp-content/plugins/woonoow/test-email-direct.php
```

This:
- Queues a test email
- Manually triggers sendNow()
- Tests wp_mail() directly
- Shows detailed output

## 🔬 Debug Logs to Check

Enable debug logging in `wp-config.php`:
```php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);
```

Then check `/wp-content/debug.log` for:

### Expected Log Flow:

```
[EmailManager] send_order_processing_email triggered for order #123
[EmailManager] Sending order_processing email for order #123
[EmailManager] send_email called - Event: order_processing, Recipient: customer
[EmailManager] Email rendered successfully - To: customer@example.com, Subject: Order Processing
[EmailManager] wp_mail called - Result: success
[WooNooW MailQueue] Queued email ID: woonoow_mail_xxx_123456
[WooNooW MailQueue] Hook registered: woonoow/mail/send -> MailQueue::sendNow
[WooNooW MailQueue] sendNow() called with args: Array(...)
[WooNooW MailQueue] email_id type: string
[WooNooW MailQueue] email_id value: 'woonoow_mail_xxx_123456'
[WooNooW MailQueue] Processing email_id: woonoow_mail_xxx_123456
[WooNooW MailQueue] Payload retrieved - To: customer@example.com, Subject: Order Processing
[WooNooW MailQueue] Disabling WooEmailOverride to prevent loop
[WooNooW MailQueue] Calling wp_mail() now...
[WooNooW MailQueue] wp_mail() returned: TRUE (success)
[WooNooW MailQueue] Re-enabling WooEmailOverride
[WooNooW MailQueue] Sent and deleted email ID: woonoow_mail_xxx_123456
```

## 🐛 Common Issues & Solutions

### Issue 1: No logs at all
**Symptom:** No `[EmailManager]` logs when order status changes

**Cause:** Hooks not firing or EmailManager not initialized

**Solution:**
1. Check `includes/Core/Bootstrap.php` - ensure `EmailManager::instance()` is called
2. Check WooCommerce is active
3. Check order status is actually changing

**Test:**
```php
// Add to functions.php temporarily
add_action('woocommerce_order_status_changed', function($order_id, $old_status, $new_status) {
    error_log("Order #$order_id status changed: $old_status -> $new_status");
}, 10, 3);
```

### Issue 2: "order_processing email is disabled in settings"
**Symptom:** Log shows event is disabled

**Cause:** Event not enabled in notification settings

**Solution:**
1. Visit: WooNooW > Notifications
2. Find "Order Processing" event
3. Enable "Email" channel
4. Save settings

**Verify:**
```bash
wp option get woonoow_notification_settings --format=json
```

### Issue 3: "Email rendering failed"
**Symptom:** `[EmailManager] Email rendering failed for event: order_processing`

**Cause:** Template not configured or invalid

**Solution:**
1. Visit: WooNooW > Email Templates
2. Configure template for "order_processing"
3. Add subject and content
4. Save template

### Issue 4: sendNow() never called
**Symptom:** Action Scheduler shows "Complete" but no `[WooNooW MailQueue] sendNow()` logs

**Cause:** Hook not registered or Action Scheduler passing wrong arguments

**Solution:**
1. Check `[WooNooW MailQueue] Hook registered` appears in logs
2. If not, check `includes/Core/Bootstrap.php` - ensure `MailQueue::init()` is called
3. Check Action Scheduler arguments in database:
```sql
SELECT action_id, hook, args, status 
FROM wp_actionscheduler_actions 
WHERE hook = 'woonoow/mail/send' 
ORDER BY action_id DESC 
LIMIT 10;
```

### Issue 5: sendNow() called but no email_id
**Symptom:** `[WooNooW MailQueue] ERROR: No email_id provided`

**Cause:** Action Scheduler passing empty or wrong arguments

**Check logs for:**
```
[WooNooW MailQueue] email_id type: NULL
[WooNooW MailQueue] email_id value: NULL
```

**Solution:**
The code now handles both string and array arguments. If still failing, check Action Scheduler args format.

### Issue 6: Payload not found in wp_options
**Symptom:** `[WooNooW MailQueue] ERROR: Email payload not found for ID: xxx`

**Cause:** Option was deleted before sendNow() ran, or never created

**Solution:**
1. Check if email was queued: `[WooNooW MailQueue] Queued email ID: xxx`
2. Check database:
```sql
SELECT option_name, option_value 
FROM wp_options 
WHERE option_name LIKE 'woonoow_mail_%';
```
3. If missing, check `MailQueue::enqueue()` is being called

### Issue 7: wp_mail() returns FALSE
**Symptom:** `[WooNooW MailQueue] wp_mail() returned: FALSE (failed)`

**Cause:** SMTP configuration issue, not a plugin issue

**Solution:**
1. Test wp_mail() directly:
```php
wp_mail('test@example.com', 'Test', 'Test message');
```
2. Check SMTP plugin configuration
3. Check server mail logs
4. Use Email Log plugin to see error messages

### Issue 8: Notification system mode is "woocommerce"
**Symptom:** No WooNooW emails sent, WooCommerce default emails sent instead

**Cause:** Global toggle set to use WooCommerce emails

**Solution:**
1. Visit: WooNooW > Settings
2. Find "Notification System Mode"
3. Set to "WooNooW"
4. Save

**Verify:**
```bash
wp option get woonoow_notification_system_mode
# Should return: woonoow
```

## 🧪 Testing Procedure

### Step 1: Check Configuration
```
Visit: /wp-content/plugins/woonoow/check-settings.php
```
Ensure:
- ✅ System mode = "woonoow"
- ✅ Email channel = enabled
- ✅ Events have email enabled
- ✅ Hooks are registered

### Step 2: Test Direct Email
```
Visit: /wp-content/plugins/woonoow/test-email-direct.php
```
This will:
1. Queue a test email
2. Manually trigger sendNow()
3. Test wp_mail() directly

Check:
- ✅ Email appears in Email Log plugin
- ✅ Email received in inbox
- ✅ Debug logs show full flow

### Step 3: Test Order Email
1. Create a test order
2. Change status to "Processing"
3. Check debug logs for full flow
4. Check Email Log plugin
5. Check inbox

### Step 4: Monitor Action Scheduler
```
Visit: /wp-admin/admin.php?page=wc-status&tab=action-scheduler
```
Filter by hook: `woonoow/mail/send`

Check:
- ✅ Actions are created
- ✅ Actions complete successfully
- ✅ No failed actions
- ✅ Args contain email_id

## 🔧 Manual Fixes

### Reset Notification Settings
```bash
wp option delete woonoow_notification_settings
wp option delete woonoow_email_templates
wp option delete woonoow_notification_system_mode
```
Then reconfigure in admin.

### Clear Email Queue
```bash
wp option list --search='woonoow_mail_*' --format=ids | xargs -I % wp option delete %
```

### Clear Action Scheduler Queue
```bash
wp action-scheduler clean --hooks=woonoow/mail/send
```

### Force Process Queue
```php
// Add to functions.php temporarily
add_action('init', function() {
    if (function_exists('as_run_queue')) {
        as_run_queue();
    }
});
```

## 📊 Monitoring

### Check Email Queue Size
```sql
SELECT COUNT(*) as queued_emails 
FROM wp_options 
WHERE option_name LIKE 'woonoow_mail_%';
```

### Check Action Scheduler Stats
```sql
SELECT status, COUNT(*) as count 
FROM wp_actionscheduler_actions 
WHERE hook = 'woonoow/mail/send' 
GROUP BY status;
```

### Recent Email Activity
```bash
tail -f /path/to/wp-content/debug.log | grep -E '\[EmailManager\]|\[WooNooW MailQueue\]'
```

## 🎯 Quick Checklist

Before reporting an issue, verify:

- [ ] WP_DEBUG enabled and logs checked
- [ ] Notification system mode = "woonoow"
- [ ] Email channel globally enabled
- [ ] Specific event has email enabled
- [ ] Email template configured for event
- [ ] MailQueue hook registered (check logs)
- [ ] Action Scheduler available and working
- [ ] SMTP configured and wp_mail() works
- [ ] Email Log plugin installed to monitor
- [ ] Ran check-settings.php
- [ ] Ran test-email-direct.php
- [ ] Checked debug logs for full flow

## 📝 Reporting Issues

When reporting email issues, provide:

1. Output of `check-settings.php`
2. Output of `test-email-direct.php`
3. Debug log excerpt (last 100 lines with email-related entries)
4. Action Scheduler screenshot (filtered by woonoow/mail/send)
5. Email Log plugin screenshot
6. Steps to reproduce

## 🚀 Next Steps

If all diagnostics pass but emails still not sending:

1. Check server mail logs
2. Check SMTP relay logs
3. Check spam folder
4. Test with different email address
5. Disable other email plugins temporarily
6. Check WordPress mail configuration

---

**Last Updated:** 2025-11-18
**Version:** 1.0