Troubleshooting Email Delivery

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.

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, 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 make sure it's being sent. In MODX, you can use a Snippet called QuickEmail to test how email is sending and get details about the response from the recipient server.

  1. Log in to the MODX Manager for the website in question.
  2. From the top menu, locate Extras>Installer and click to open the Installer
  3. Click Download Extras
  4. In the Download Extras view, enter QuickEmail in the search field and hit Enter/Return
  5. Quick Email will appear; click to Download it
  6. Click Back to Package Management from the top left of the view
  7. Find QuickEmail from the list; you may need to go to another page if you have many Extras installed
  8. Click Install to install Quick Email and follow the steps
  9. 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).Editing_Email_Test__jaygilmore.ca_2019-07-04_15-04-50.png
  10. Add the following QuickEmail Snippet call to the content field of the page:
    [[!QuickEmail? &debug=`1`]]
  11. Save the Document and then Click View from the top right
  12. The page should display the results of an email send using the System Settings for EmailMozilla_Firefox_2019-07-04_15-12-29_1_.png

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.

  1. Log into your Cloud via SSH or SFTP
  2. Create a new file via SSH (SFTP is below):
    1. Navigate to the /www/ directory and use the following command:
      nano mailtest.php
    2. This will open the nano editor, and you can copy the code below and paste into the nano view:
      * 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";
      echo "Error: Message not accepted";
    3. Click CTRL+X to close and then Enter/return to save the file with the filename mailtest.php
  3. 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.
  4. 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
  5. Add the mailtest.php to the end of the URL (changing the address to your URL) as follows:
  6. 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, 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.


Have more questions? Submit a request


Article is closed for comments.