Troubleshooting Email Errors

If Craft is having trouble sending emails, you’ll need to ensure that everything is configured correctly.

First we need to get Craft to attempt to send an email, so we can narrow down where the problem is. In the Control Panel, go to Settings → Email, scroll down to the bottom of the page, and click the “Test” button. One of two things will happen here: either Craft will think that the email sent successfully, or an error will occur.

When Craft thinks that the email was sent successfully, you’ll get a blue notification message that says “Email sent successfully. Check your inbox.” at the top of your browser window. If you’re seeing that but the email isn’t reaching your inbox, jump to the Dealing with Email Delivery Issues section below. Otherwise continue reading…

Dealing with Errors #

Craft 2.6.2788 made it easier to identify email errors. Make sure you’re running that version (or later). If not, update Craft and then click the “Test” button again.

You will see one of two error notification messages when something goes wrong on Craft’s end:

“There was an error testing your email settings” #

This occurs when an exception was thrown at some point in the email-sending process. You’ll be able to find more details about the exception in Craft’s logs. Open up craft/storage/runtime/logs/craft.log and search for this text:

[exception.Craft\EmailTestException]

It will be part of a log entry that identifies exactly what went wrong. Here’s an example:

2016/05/19 23:35:35 [error] [exception.Craft\EmailTestException] exception 'phpmailerException' with message 'SMTP connect() failed. https://github.com/PHPMailer/PHPMailer/wiki/Troubleshooting' in /path/to/craft/app/vendor/phpmailer/phpmailer/class.phpmailer.php:1464

If you can’t find the log entry, it may have already been pushed out to another log file (craft.log.1, craft.log.2, etc). You can search through the other files, or click the “Test” button again and reload craft.log immediately after getting the error notification.

Here are a few common exception messages, and what they mean:

ErrorExplanation
Invalid address: [email]The System Email Address or your user account’s email address is invalid.
Could not instantiate mail function.The Protocol was set to either “PHP Mail” or “Sendmail” but PHP is not configured for those protocols. Contact your host for help.
SMTP connect() failed.The Protocol was set to “SMTP” but Craft could not connect with the provided settings, or a firewall/antivirus software is blocking the request.
SMTP Error: Could not authenticate.“Use SMTP authentication” was checked, but the credentials were incorrect.
SMTP Error: Could not connect to SMTP host.“SMTP Secure Transport Type” was set to “TLS”, but Craft could not establish a secure connection to the email server.

“An unknown error occurred” #

You’ll get this error when a fatal PHP error occurred, which Craft wasn’t able to recover from. Check craft/storage/runtime/logs/phperrors.log and look for a recent log entry to find out more. You may need to contact support@craftcms.com for help with this one.

Dealing with Email Delivery Issues #

If Craft acts like everything worked great after clicking the “Test” button, but the email never makes it to your inbox, there are several things to check:

  • Check any junk/spam folders.
  • Make sure the domain you're sending the email from has valid reverse pointer DNS records, is using Domain Keys Identified Mail and has an SPF/Sender ID DNS record (what?).
  • If you’re using the PHP Mail or Sendmail protocols, don’t. They are notoriously unreliable at successfully delivering emails and should not be used in a production environment. Consider using a proper SMTP server, or better yet, a transactional email provider like Postmark, Mailgun, or Sparkpost, all of which support SMTP connections.