Email delivery troubleshooting guide

This document is aimed at guiding users through the solution of many different email delivery problems, including but not limited to:

• I get an error while sending the email, which makes clear that the email has not been sent
• I get no error, and yet no email arrives to the recipient, which includes 2 sub-cases:
  1. The delivery has failed in a point which does not produce a visible error message
  2. The email has been classified as spam on the way

There are also exotic cases

• The submitter receives his copy to his private email address, but the site owner doesn’t receive his copy to his corporate email address.
• The other way around, emails are delivered to mailboxes which belong to the website domain, but nothing comes to “external” email addresses.

Whatever your problem is, pay particular attention to the step 1 (Obtain the documentation), since 99% of the email delivering problems found their solution there.

Content index

Introduction
0. Running on local workstations or developer's machines
1. Obtain the documentation
2. Test the Joomla Mailer
3. Consult the events log
4. Enable SMTP debug
5. Emails arrive to some people but not to others
6. Try an external SMTP
7. Check for disabled network functions

Introduction

In order to troubleshoot email delivery problems, it’s important to understand how email delivery works.
Let’s take a look to the elements involved and their roles.

1. Fox Contact, which is just a form builder, generates the email message and passes it to Joomla.
2. Joomla, in turn, being just a CMS, passes the email message received to your SMTP server, through the PHPMailer library or the PHP mail() function, depending on the settings found under “Global Configuration” → “Server” → “Mail Settings”.
3. Your SMTP server, which is a mail transfer agent, is the sole subject able to route the email received up to the recipient’s SMTP server, which finally delivers the message to the recipient’s inbox, or spam folder at its discretion, based on elements described in details later in this document.

It’s worth pointing out that Mail Transfer Agents are normally the only programs with the authority to route emails through the Internet.

Summary diagram
Fox Contact → Joomla → PHPMailer library or PHP mail() func → sender’s SMTP server


0. Running on local workstations or developer's machines

If you are running Joomla on your local workstation or development machine, it’s quite common to experience email delivery failures, because local hosts are often misconfigured, and get mistaken for spam servers.
In this case, you have basically 3 different options:

Option 1: Don’t care
Just don’t care, and try again after moving the site to the production server

Option 2: Configure properly your local host with an external SMTP server
On Windows wamp / xampp local environments, as well as on Linux or macOS developer machines, the PHP mail() function never works out of the box, until you don't set properly the correct values in php.ini, and restart apache service.Option 3: Configure Joomla with an external SMTP
If you are not able to fix Apache settings, configure your Joomla website to use an external authoritative SMTP server, for which you have valid credentials, as if Joomla was your email client.
If you do so, note that due to GMail restrictions, if you have enabled 2-Step-Verification, you need to generate and use an App Password in order to send emails from Joomla. Other providers may apply similar restrictions.




1. Obtain the documentation

Pay particular attention to this step, since the 99% of the email delivering problems found their solution here.

Each Hosting Provider (abbreviated Provider) may require its own email settings, which may or may not be unique for each domain.
Search for the official documentation written by your provider about the correct email configuration you should use.
While checking your email settings, remember that Fox Contact uses parameters specified in "Mail Settings" under "Joomla Global Configuration", unless different values are specified in "Global Configuration" > "Fox Contact" > "User email notification", which override the default.
Pay attention, if the form stopped working recently, your provider has most likely changed the server infrastructure. Ensure to obtain the most recent documentation.

Did you follow the email configuration instructions by your Provider?

No, I can't find any documentation about email settings on my domain or Provider.
Contact your Provider and ask for the email settings you have to use on your host or domain.

Yes, I'm sure that my configuration is correct.
Continue reading.


2. Test the Joomla Mailer

Fox Contact relies on the Joomla Mailer subsystem, so probably your Joomla itself is unable to send email.
Test this using "Users" → "Mass Mail Users". There, send a message to some groups.
Also, give it a try with "Global Configuration" → "Server" → "Mail Settings". There press the "Send test email" button.



Does the email arrive to your inbox?

No, the message doesn't arrive.
This means that the problem isn't limited to Fox Contact: your Joomla site is unable to send emails at all. Fix your Joomla mailer, and Fox Contact will automatically start working as well.
Ask for help on forum.joomla.org telling that Joomla doesn't send email at all.

Yes, I receive mass emails from my Joomla website.
It seems that the problem is limited to Fox Contact. Continue reading.


3. Consult the events log

Fox Contact logs all its activities in a plain text file named foxcontact.php under your Joomla logs directory, which is /logs or /administrator/logs depending on your Joomla configuration. The file is protected from unauthorised accesses over the web with a browser, so use FTP protocol to download it.

Does it contain any error messages?

Yes, it contains the message "Error sending email".
It seems that your Joomla Mailer subsystem doesn't accept email. It may be affected by one of the problems mentioned below. Continue reading.

No error, it only contains the message "Email sent".
The email has been successful passed to your Joomla Mailer subsystem. It is probably being blocked in a subsequent phase. Continue reading.


4. Enable SMTP debug

What makes so hard the troubleshoot of email delivery, is the lack of information about what the Joomla email subsystem and your mail server are saying to each other. You can't know if the mail server denies the message for a trivial reason until you enable SMTP debug, disclosing the transcription of the SMTP communication between the Joomla email subsystem and your mail server as plain text.
Activate the SMTP debug by editing the file libraries/phpmailer/phpmailer.php (on Joomla 3.4 and newer the file is libraries/vendor/phpmailer/phpmailer/class.phpmailer.php)
Search for the variableand change it toNow, when submit a contact form, you'll see in your browser the reason why your mail server refuses to work.
For obvious reasons this tip only applies to "SMTP" mailer in Joomla Global configuration; there is no way to debug the communication protocol for "PHP mail" or "Sendmail" mailer configurations.


5. Emails arrive to some people but not to others

Emails are delivered to the sender, while they are not delivered to email addresses which belong to the domain involved.
The mx records of your domain point to a dedicated email server, but your web server is erroneously configured to handle itself emails for that domain.
As a consequence, emails directed to external domains are regularly delivered through external SMTP servers, while emails directed to your domain remain blocked there and never reach your actual mx server, which runs on a different host.
Hostgator's customers reported that reconfiguring the MX record to "remote email server" in their cPanel solves the problem.


Emails are delivered to mailboxes which belongs to the website domain, but nothing comes to “external” email addresses.
This is probably caused by a bad network configuration of the mail server used by Joomla, which suffer either difficulties in resolving DNS names, or difficulties determining external routing table, but it can resolve names and determine routes, when it comes to internal network destinations.

In both cases there are serious issues with the network infrastructure of your website and domain that you should solve with care and under the guidance of your network administrator.

If your website is hosted on a well known hosting provider, chances are that you are just using a wrong email configuration. In this case go back to the step 1: Obtain the documentation from your hosting provider for a proper email sending settings.

6. Try an external SMTP

If you are unable to setup your SMTP subsystem, try using a reliable authenticated external SMTP server, such as GMail.
If you do so, note that due to GMail restrictions, if you have enabled 2-Step-Verification, you need to generate and use an App Password in order to send emails from Joomla. Other providers may apply similar restrictions.

"Global configuration" > "Mail Settings"


Does the email arrive to your inbox now?

Yes, I receive contact emails now.
You have a problem at Mail Transfer Agent (MTA) level. Ask your Provider to solve the problem, or continue using your external SMTP server.

No, Fox Contact is still unable to send emails.
Your server is probably behind a firewall and you haven't any chance to get it working by yourself. Contact your Provider and tell them all your attempts. They should be able to give a solution.


7. Check for disabled network functions

If you are using SMTP protocol, ensure that

1. the network-related PHP functions have not been disabled and
2. your server is not behind a firewall that blocks outgoing network connections

Note: Even when the email delivery works, remember that the email protocol is an unreliable delivery service.
For that reason, always enable database messages storage with Joomla Messenger in addition to email delivery.