Note: This blog post was first published in German only on 24 January 2016. I’ve only translated it on 29 December 2024, updated some things in text and also created new screenshots. The solution presented in this blog post still works with current versions of Contact Form 7.

This week I received a report of an error on a website related to the very popular contact form plugin Contact Form 7. In this post, I’d like to briefly explain what exactly the error was (so you don’t make it too) and how to better debug errors with the plugin.

Finding the error

Most of the time you only get a message from someone saying something like “I can’t submit forms”. So you first must find out for yourself what exactly is not working with the form. Troubleshooting was not exactly easy, as the plugin does not provide much information about what went wrong in the event of an error. All you get is this message:

That doesn’t really help me as the site administrator either. So the first thing I did was to create a new form. Of course, it worked perfectly with this one. So my next idea was to gradually copy the settings of the other form until the error occurs. In the meantime, however, I saw the error. Here are the settings from the form that didn’t work:

Well, who can see the error? I didn’t notice it immediately, either. The error is in the “From” field. This is where the sender address is defined. This can either be just an email address or a “display name” and an email address in angle brackets. Instead, there is only the domain in brackets, which is not a valid email address and therefore leads to an error when trying to send the email.

The solution

To solve the problem, you only need to enter a valid address here. The field normally looks like this:

[your-name] <[email protected]>

However, the site owners had probably changed the address themselves, as they only wanted to display the domain for the recipient, which then led to the error. With Contact Form 7, it is possible to send two emails. One to the site owners of the page and a copy to the sender of the form. Therefore, it will actually make much more sense if the email comes from the sender’s address (if an email field is included in the form). The field should look like this:

[your-name] <[your-email]>

Debugging errors

The Contact Form 7 documentation recently added an entry for this type of error, but if there are other problems, the error message page doesn’t really help.

I therefore inspected the plugin code and WordPress Core a bit, to see if there is a way to easily debug such an error. Since WordPress 4.4 there is a filter wp_mail_failed, but it is quite useless here as it does not provide any error information for this type of exception. However, there is also a hook from Contact Form 7, which we can use like this:

function debug_cf7_add_error( $items, $result ) {
	if ( 'mail_failed' == $result['status'] ) {
		global $phpmailer;
		$items['errorInfo'] = $phpmailer->ErrorInfo;
	}

	return $items;
}
add_action( 'wpcf7_ajax_json_echo', 'debug_cf7_add_error', 10, 2 );

If an error occurs, we read the error from the global $phpmailer object and add it to the AJAX response. We can then debug the error in the frontend, e.g. using Chrome’s DevTools:

Conclusion

Sometimes it really isn’t that easy to find an error. In those cases, it really helps, if the plugin offers a good debugging function to detect such errors. Validating the settings when creating the contact forms would also have helped a lot here.

As in previous blog posts from my advent calendar, I have also created a GIST with a plugin for you, which you can download and install as a ZIP file.

If you know of similar errors, and have a simple solution for them, please leave a comment below. There are also some comments on my German blog post, which you might find helpful – after translating them. 😁

Update: 29 December 2024

I have updated the screenshots and error messages with the new versions of Contact Form 7, WordPress and Chrome. I also took the opportunity to convert the post into blocks. After almost 9 years, this post simply needed a little attention, as it is still one of the most read posts here on the blog.

For some versions, Contact Form 7 now also has a function that automatically detects errors in the configuration. The error from 2016 described in this article would therefore have been noticed immediately. However, there may of course be other errors that you want to debug.