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:

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:

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:

// 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:

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:

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:

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:

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:

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

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

wp option list --search='woonoow_mail_*' --format=ids | xargs -I % wp option delete %

Clear Action Scheduler Queue

wp action-scheduler clean --hooks=woonoow/mail/send

Force Process Queue

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

📊 Monitoring

Check Email Queue Size

SELECT COUNT(*) as queued_emails 
FROM wp_options 
WHERE option_name LIKE 'woonoow_mail_%';

Check Action Scheduler Stats

SELECT status, COUNT(*) as count 
FROM wp_actionscheduler_actions 
WHERE hook = 'woonoow/mail/send' 
GROUP BY status;

Recent Email Activity

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