Troubleshooting Email Delivery – MODX Cloud Support

If your site is not sending email as it should be this document will help you figure out why.

This document is valid for any website in MODX Cloud. However, some of the troubleshooting will be specific to MODX CMS.

SMTP Email Ports

Port 25 is blocked in MODX Cloud as a measure to prevent email abuse and spam. Most SMTP can go over alternative ports, like 465, 587 or 2525. This is configured in the MODX System settings (search for "mail_smtp_port").

SPF Records

Mail providers frequently send email to spam that doesn't have a strong SPF record. To learn more about setting up and validating SPF Records, please see our SPF KB Article.

The Reliability of Email Methods

If email sending is critical to your website, an Email Service Provider (ESP) is the most reliable way to send emails with MODX or your application. Webmail SMTP (Gmail, GSuite, Outlook.com) is reasonably reliable. However, configurations can change over time, and things may stop working. The least reliable method is using a web server's built-in mail application because it can drop emails, doesn't provide logs, and there can be issues because of IP reputation. ESPs provide antispam protection, deliverability optimization and most importantly, a proper record of the email delivery flow. Learn more about email in MODX Cloud.

Diagnosing Issues

Is MODX Sending the Email?

The first step in troubleshooting email delivery is to ensure it's actually sending. In MODX, you can use a Snippet called QuickEmail to test how email is sent and see details about the response from the recipient server.

Log in to the MODX Manager for the website in question.
From the top menu (or left-side in MODX 3.0+), locate Extras > Installer and click to open the Installer.
Click the Download Extras button.
In the Download Extras view, enter QuickEmail in the search field and hit Enter/Return key.
QuickEmail will appear; click to download it.
Click Back to Package Management from the top left of the view.
Find QuickEmail from the list; you may need to go to another page if you have many Extras installed.
Click Install to install Quick Email and follow the steps.
Once the installation is complete, from the Resource Tree, Create a new Document (Resource) and give it a name. Make sure it's set to "Hidden from menus", and it's easiest if you do not assign a Template to it (make the template empty).
Add the following QuickEmail Snippet call to the content field of the page:
```
[[!QuickEmail? &debug=`1`]]
```
Save the Document and then Click View from the top right
The page should display the results of an email send using the System Settings for Email

As you can see you get a report of the fail and the reason the sending server says it failed. You might also get other errors. These errors will help you figure out why the email is not sending or not getting through.

Is PHP Sending Email in MODX Cloud

If you're using another application in a Flex Cloud and you wish to test to see if MODX Cloud is sending email, follow these steps to do so. This requires you can connect to your Cloud using SFTP or SSH. If this is not something you know how to do, please contact us for assistance.

Log into your Cloud via SSH or SFTP

Create a new file via SSH (SFTP is below):

Navigate to the /www/ directory and use the following command:
```
nano mailtest.php
```

This will open the nano editor, and you can copy the code below and paste into the nano view:

<?PHP
/*
 * Simple PHP Script to test email sends
 */

// Change the emails here:
$sender = 'someone@somedomain.tld';
$recipient = 'you@yourdomain.tld';

$subject = "php mail test";
$message = "php test message";
$headers = 'From:' . $sender;

if (mail($recipient, $subject, $message, $headers))
{
 echo "Message accepted";
}
else
{
 echo "Error: Message not accepted";
}
?>

Click CTRL+X to close and then Enter/return to save the file with the filename mailtest.php

If using an SFTP client such as FileZilla, Cyberduck, CuteFTP or Forklift,
1. navigate to the /www/ directory and then right-click or use the File Menu to create a new file.
2. Right-click on the file to open it in a text editor (this can't be Notepad on Windows as it will save files with a .txt file extension).
3. Paste the code above in the file and save.
Once the file's been placed via one of the methods above, visit the website in your browser via the main URL or the Cloud URL
Add the mailtest.php to the end of the URL (changing the address to your URL) as follows:
```
https://changetoyourdomainname.com/mailtest.php
```
In the browser you should see either the email sent or the error message: "Error: Message not accepted"

If mail is not working as it should be, please contact us for assistance.

The Site is Sending, But Email is Not Received

If you're getting a successful send from in the section above with QuickEmail, the next thing to do is to figure out why the emails are not showing up in the inbox as expected.

If you are using an ESP, you'll want to review the logs to see if the emails were sent.

If you are using SMTP via webmail such as Gmail, GSuite or Outlook.com/Office365, you should be able to review the Sent folder from your webmail client or desktop Client if you have the email address in question configured there.

Deliverability is Success is Reputation

For sites relying on the server's email, deliverability issues are almost always related to email reputation. Email reputation is a large topic and can get complex fast. A method to check your email reputation for the email and server sending the emails is to run the email address and domain name of the website through a tool such as the SuperTool at MXToolbox. This will identify issues such as no SPF Records or IP address (see Email in MODX Cloud for more detail about IP Reputation Management), or domain name is on a blocklist.