WooCommerce failed-order email troubleshooting gets harder when the final recipient value is not recorded. A short-lived snapshot can preserve the email class, order transition, recipient label, filter result, and mail outcome without storing message content or exposing customer addresses.
Use this when failed-order emails reach an admin but not a customer, when recipients change after custom filters run, or when the WooCommerce log and SMTP provider appear to disagree.
Quick answer
WooCommerce Failed Order Recipient Snapshot Log should be handled with a narrow evidence-first workflow: create one test order, capture filter output, redact recipient data, then verify the result before making broader changes.
What to check first
- Create one controlled failed order and record the order ID, payment method, transition time, and expected email class.
- Capture the recipient immediately before and after custom WooCommerce recipient filters run.
- Store a redacted recipient label, not a raw customer address, with the filter callback and request ID.
- Match the snapshot to the transactional-emails log, wp_mail result, and SMTP message ID.
- Remove the temporary logger after one successful retry and preserve only the incident summary.
Diagnostic table
Use this table to keep the work practical. It connects the symptom to evidence and a verification step.
| Action | Evidence to collect | How to verify |
|---|
| Create one test order | Create one controlled failed order and record the order ID, payment method, transition time, and expected email class. | The final snapshot shows one intended recipient for the failed-order email class. |
| Capture filter output | Capture the recipient immediately before and after custom WooCommerce recipient filters run. | WooCommerce and SMTP timestamps refer to the same controlled order and attempt. |
| Redact recipient data | Store a redacted recipient label, not a raw customer address, with the filter callback and request ID. | The customer receives one message and no duplicate admin or customer email is created. |
| Match mail evidence | Match the snapshot to the transactional-emails log, wp_mail result, and SMTP message ID. | The temporary code and raw debug data are removed after verification. |
Why this usually happens
- Recipient filters can return an empty string for an email class they do not recognize.
- Order status code can trigger a different email than the operator expects.
- SMTP evidence starts after WooCommerce has already decided who receives the message.
- A later retry can hide the recipient value from the original failed attempt.
Useful command or data shape
Adapt paths, IDs, and privacy handling to the site before running commands or storing data on production.
add_filter( 'woocommerce_email_recipient_failed_order', function ( $recipient, $order ) {
error_log( wp_json_encode( [
'order_id' => $order ? $order->get_id() : 0,
'email_class' => 'failed_order',
'recipient_state' => $recipient ? 'present' : 'empty',
] ) );
return $recipient;
}, 999, 2 );
Safe fix order
Do the work in a sequence that makes each result easy to prove. Stop if a step produces new evidence that changes the incident scope.
- Create one test order
- Capture filter output
- Redact recipient data
- Match mail evidence
- Remove temporary logging
What to tell the client or owner
Report the order ID, email class, filter callback, redacted recipient state, mail result, SMTP message ID, and retry outcome.
Production verification checklist
- The final snapshot shows one intended recipient for the failed-order email class.
- WooCommerce and SMTP timestamps refer to the same controlled order and attempt.
- The customer receives one message and no duplicate admin or customer email is created.
- The temporary code and raw debug data are removed after verification.
Mistakes to avoid
- Do not judge the fix by one browser or the homepage only.
- Do not delete evidence before recording usernames, file paths, timestamps, and response headers.
- Do not add a cache, security, or tracking plugin while the original problem is still unclear.
- Do not leave test users, temporary debug logs, or broad API keys active after verification.
When HandL WP should help
Bring in help when this affects leads, checkout, search visibility, malware risk, paid media reporting, or a client production site. HandL WP can trace the issue through WordPress, hosting, cache, tracking, and Search Console, then verify the workflow after the technical fix.
If this is active on a production site, trace WooCommerce email delivery from order to mailbox.
Related HandL WP guides
Use these related guides when the same issue touches tracking, security, checkout, or crawler visibility.
Helpful references