Debugging Wp Mail like a boss debugger

D

Have you ever had problems with sending mail from your WordPress site with no apparent reason? It is really hard debugging WP mail as it just returns true or false depending on the function’s result.

Recently I had similar problems and it took me some time to dig through the WordPress core code and try to get what is the actual error and actual debugging WP mail messages when trying to send email.

I am writing a solution here, so next time you have these problems, you will get to the error message sooner and I hope it will save you some time.

Prepare WordPress error logging

Before actually starting to debugging, I like to setup WordPress to write error messages to error log, rather than on the screen.

To do that, open your wp-config.php file and put this in:

/**
 * This will log all errors notices and warnings to a file called debug.log in
 * wp-content (If Apache does not have write permission, you may need to create
 * the file first and set the appropriate permissions (i.e. use 660) )
 */
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

Now, all errors, warnings and notices will be written to a debug.log file which will be located in your wp-content folder.

If you want more tricks from wp-config.php file, you can go to Editing wp-config settings.

To test, you can add this code somewhere in functions.php file:

error_log('testing if error log is working');

The above text should be visible when you refresh your page inside debug.log file in wp-content folder.

Please make sure to put WP_DEBUG to false after testing is done.

Debugging WP Mail (after WordPress 4.4)

WordPress added a handy little hook in version 4.4 called wp_mail_failed.

Simply add this code to your functions.php or plugin file:

// define the wp_mail_failed callback 
function action_wp_mail_failed($wp_error) 
{
    return error_log(print_r($wp_error, true));
}
         
// add the action 
add_action('wp_mail_failed', 'action_wp_mail_failed', 10, 1);

This will log all information about wp_mail errors, as well as all parameters used in sending email.

Debugging WP Mail (before WordPress 4.4)

If you are using WordPress version older than 4.4 (I hope you are not, but just in case), add the following code to actually debug wp mail:

// your line which sends an email
$result = wp_mail($sendto, $subject, $content, $headers);

// wp mail debugging
if (!$result) {
    global $ts_mail_errors;
    global $phpmailer;

    if (!isset($ts_mail_errors)) $ts_mail_errors = array();

    if (isset($phpmailer)) {
        $ts_mail_errors[] = $phpmailer->ErrorInfo;
    }

    error_log(print_r($ts_mail_errors, true));
}

It will output something like this (in my case it was this error):

[19-Jan-2017 10:06:23 UTC] Array
(
    [0] => SMTP Error: data not accepted.SMTP server error: DATA END command failed Detail: 5.7.60 SMTP; Client does not have permissions to send as this sender
 SMTP code: 550
)

I hope this helps someone.

About the author

Zvonko Biškup

A passionate web developer with more than 13 years experience in PHP and other web related technology. My main interest is WordPress and new PHP frameworks.
Owner of Influendo Programming.
Enjoys exploring new stuff and possibilities, using new technologies and just having fun developing awesome stuff.

  • Oasis Workflow

    Nice article.

    WordPress also has wp_mail_failed() hook. Is there any particular advantage in doing the way you explained over implementing the hook and simply logging the WP_Error object, which is part of the action parameter.

    • Thanks for your comment. Yes, WordPress introduced the hook in 4.4, there is no advantage in my implementation, except it is working for older installations of WordPress, but will update the article to include this hook as well.

  • Dylan Hamilton-Foster

    Thanks for this – but when you say: Now, all errors, warnings and notices will be written to a debug.log file which will be located in your wp-config folder. you mean wp-content folder.

By Zvonko Biškup

Tags