Troubleshooting Email Errors
Craft may not be able to send email for a number of reasons. Let’s look at some common causes and methods for troubleshooting them.
First, we need to get Craft to attempt to send an email to narrow down where the problem is. In the control panel, go to Settings → Email, scroll down to the bottom of the page, and press Test. 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 test email was sent successfully, you’ll get a confirmation flash message that says “Email sent successfully. Check your inbox.” If you’re seeing that but the email isn’t reaching your inbox, jump to the Dealing with Email Delivery Issues section below. Otherwise, it’s time to chase down an error message…
Dealing with Errors #
You will see one of two error notification messages when something goes wrong on Craft’s end:
“Your email settings are invalid” #
This points to a failure prior to actually sending the test email, like an improperly-formatted System Email Address, or a missing value for the selected adapter.
Review the settings screen for errors, and try again.
“There was an error testing your email settings” #
This occurs when an exception was thrown while attempting to send the test email. You’ll be able to find more details about the exception in Craft’s logs. Open up the latest web-* log file in storage/logs/ (usually something like web-2023-04-20.log), and search for one of these strings:
[yii\symfonymailer\Mailer::sendMessage]
[web.ERROR]
It will be part of a log entry that should identify exactly what went wrong. Here’s an example:
2023-04-21 22:20:59 [web.ERROR] [yii\symfonymailer\Mailer::sendMessage] Connection could not be established with host "127.0.0.1:1234": stream_socket_client(): Unable to connect to 127.0.0.1:1234 (Connection refused) {"memory":2123952}
This error suggests that our SMTP hostname or port is wrong. We took this error directly from a Craft 4 installation running in DDEV that was supposed to be connecting to the provided Mailhog instance, on port 1025.
If you anticipate needing to test settings a number of times while troubleshooting, you can run tail -f storage/logs/web-*.log | grep "web.ERROR" -C 10 to monitor the output, filtered by a string.
Read more about interpreting logs in the documentation.
Here are a few common exception messages, and what they mean:
| Error | Explanation |
|---|---|
| Unsupported sendmail command flags. | The adapter was set to sendmail, but there was a problem interpreting a flag or argument. Consider reverting to the default command, /usr/bin/sendmail -bs for further testing, or consult your host for the proper usage. |
| Connection could not be established with host… | The Protocol was set to “SMTP” but Craft could not connect with the provided settings, or a firewall/antivirus software is blocking the request. |
| Failed to authenticate on SMTP server with… | “Use authentication” was enabled for an SMTP connection, but the credentials were incorrect. |
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 (or one of your users’ inboxes), there are several things to check:
- Did it end up in a junk/spam folder?
- 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. Postmark has a great article on this.
sendmailis notoriously unreliable and should not be used in a production environment. Consider using a proper SMTP connection or—better yet—a transactional email service like Postmark, Mailgun, or Sendgrid, all of which support SMTP and HTTP APIs.