Skip to content

How to detect the issue behind a wp_mail() failure

How to detect the issue behind a wp_mail() failure

wp_mail() function Not Working but Everything Looks Right

How to detect mail issues and expand error logging information by using the wp_mail_failed hook.

How to detect the issues behind a wp_mail() failure.

The wp_mail_failed hook fires after a PHPMailer\PHPMailer\Exception is caught.

This code snippet below will hook into the wp_mail_failed hook and log the issue.

// show wp_mail() errors
public function mail_failure( $wp_error ) {
error_log( 'Mailing Error Found: ');
error_log( print_r( $wp_error, true) );
}
add_action( 'wp_mail_failed', 'mail_failure', 10, 1 );

This little snippet of code is such a life saver. Add this to your functions.php file and turn on the debugging log and you’ll soon see the issues behind your mailing woes.

This little snippet saved me. I had a malformed ‘From’ email address. However, no errors were being produced in the errorlog other than the false boolean that would return from wp_mail().

The solution, as I came to find out, was that I had needed to update my mail headers from address to a valid email address. I was testing in a local testing environment, so it would make sense that the wordpress@localtestdev would not work.

What does the WP Mail failure Error look like?

wp_mail_failure produces an error object from WP Error. It will return an object with an ‘errors’ array, inside of which will be the wp_mail_failed array that will contain our error message.

[errors] => Array
( [wp_mail_failed] => Array
( [0] => Invalid address: (From): wordpress@localtesdev ))
[error_data] => Array
( [wp_mail_failed] => Array
( [to] => Array ( [0] => hello@joshbrown-designs.com )
[subject] => Your New Product Notifications
[message] => ‘Email Message’

We can see that our email failed because of an invalid From Address and the address that is invalid.

To add a From or Reply-To email address when sending an email using wp_mail() we include that information in the email headers. This solution also works if we want to include the Bcc or if we want to use html mark-up in our email template.

How to Update your mail headers when using wp_mail()

The simple answer is that we create a string, or array of strings, to configure the header settings and pass that to the wp_mail function.

The codex gives us this example from wp_mail():

$headers[] = 'From: Me Myself <me@example.net>';
$headers[] = 'Cc: John Q Codex <jqc@wordpress.org>';
$headers[] = 'Cc: iluvwp@wordpress.org';

( Side-note: Check out the way they are adding to the $headers array. For me, this was definitely a new way to add strings to an array. )

Okay, great. Given this example, we can simply create an array of strings for each line. This example doesn’t explicitly show it, but one could assume that adding a string with Bcc: – that would give you a Blind Carbon Copy if you so desired.

$mail_status = wp_mail( $to, $subject, $body, $headers );

It works! Once I had this figured out I was able to add a ‘From address’, ‘From name’ as well as ‘Reply-To’ information plus configuring rendering for HTML.

Adding email information in the headers with variables

Below is the solution I finally came to finally be able to send out my email but also render the HTML template I was generating in the email.

Since the piece of code is a template, I need it to have variables in place for production, however the code is the same as above. We are still creating an array of strings to pass as the third parameter.

$headers[] = "From:{$fromName} <{$fromEmail}>";
$headers[] = "Reply-To:{$replyName} <{$replyEmail}>";
$headers[] = "Bcc:{$bccEmail}";
$headers[] = "Content-Type: text/html; charset=UTF-8";