Troubleshoot SMTP Issues
Introduction
Most applications require sending a mail to users at some point, for example:
- New user registration in WordPress
- Issue creation in Redmine
- Password recovery in Joomla!
These features are essential in a production environment. The application communicates with a Simple Mail Transfer Protocol (SMTP) server, which transfers the mail through the Internet. In almost every application in the Bitnami catalog, you must configure the SMTP by setting the following properties:
- SMTP server host: The SMTP server address.
- SMTP server port: The SMTP port that accepts requests.
- Credentials: The username and password authenticated by the SMTP server.
- Security protocol: Establishes the encryption and secure protocol that the SMTP server uses to communicate.
- Sender address: The address that the mails originate from. This does not have to be the same as the previously mentioned username.
Here are some examples of SMTP providers:
Bitnami stacks do not come with the SMTP settings pre-configured, therefore you must manually configure the settings yourself. You can do this in either of the following ways:
- Using the application administration panel.
- Modifying the application configuration files through SSH. This method is more error-prone.
An SMTP issue can arise when your application tries to send a mail (for example, when a user clicks on the “Password Reset” button) and it never reaches the recipient’s mailbox.
How to detect
SMTP issues are very easy to detect. Using any application feature that sends mail, send a mail. If the mail never arrives in the recipient’s inbox, there is something wrong with the SMTP. Some applications provide more information about the issue, others show no errors. The following are examples of SMTP error messages:
Common issues
The following are the most common SMTP issues that Bitnami users face:
- SMTP configuration: The application’s SMTP settings are misconfigured (parameters, syntax, etc.).
- SMTP provider: Some SMTP providers require special configuration steps to send mails from cloud applications. For example, Google Mail requires you to enable insecure 3rd Party Apps integration. For more information about how to troubleshoot Gmail SMTP issues for your specific application, refer to the troubleshooting steps in our application documentation.
- Application: Sometimes the issue is in the application itself (not in Bitnami configuration), for example, incompatible encryption protocol, application bugs, etc.
- Infrastructure: Some clouds may block mail traffic for security reasons. For example, because of potential SPAM abuses, Google Cloud does not allow traffic on port 25. Other examples of infrastructure issues include misconfigured firewalls (so the instance cannot access the SMTP Server) or wrong server datetime.
Troubleshooting checklist
The following checklist covers the majority of the cases described above and will help you to find and debug most SMTP issues.
Is your mail provider configured correctly to allow SMTP applications?
Some mail providers such as Gmail require special steps to allow SMTP connections for applications. Check your mail provider’s SMTP documentation. The following are links to the most common SMTP documentation:
Amazon EC2 blocks SMTP port 25 by default on all Amazon EC2 instances, and you must manually request removal of this restriction to use this port.
Can your instance connect to the SMTP server?
Your instance may have connectivity problems with the SMTP server. You can check the connection by following these steps:
-
Log into your instance through SSH.
-
Install the Telnet client using your system package manager.
-
Execute the following command (substituting the SMTP_HOST and SMTP_PORT placeholders):
$ telnet SMTP_HOST SMTP_PORT -
If the connection is correct, you will see an output similar to the following:
Trying 74.125.206.108... Connected to [...] Escape character is '^]'. -
If you get errors in the command, then SMTP is not working because the application cannot connect to the SMTP server. There are different causes for this, such as firewall configurations, VPN restrictions or DNS settings. For more help on this issue, contact your cloud provider.
Does your cloud allow traffic in SMTP Ports?
To avoid massive SPAM attacks, several clouds do not allow SMTP traffic in their default ports. The following are two examples:
- Google Cloud Platform does not allow SMTP traffic through default port. To learn how to use a different port for sending emails from your application, see the Google Cloud documentation .
- GoDaddy also blocks SMTP traffic. This link provides you with on how to configure SMTP in this cloud.
If SMTP traffic is blocked, you will have issues connecting to your SMTP server. For more advice on how to allow SMTP traffic, contact your cloud provider.
Are the application SMTP settings set correctly?
The most common cause of SMTP failures is because of a wrong outbound mail configuration. Check the following:
- You introduced the following parameters in the SMTP configuration:
- SMTP Host
- SMTP Port
- SMTP Username
- SMTP Password
- SMTP Encryption
- Check that these parameters are those provided by your mail provider.
- Check that you have followed the “Configure outbound mail settings” section in the application documentation page.
Is your custom SMTP server working?
If you are using a custom SMTP server, you can use tools such as Wormly to test your server. If this tool is not working, you may have misconfigured the SMTP server.
Does your server have the correct date/time?
Some operations require that the server has the correct date and time, otherwise they fail. To check the date and time, execute the following command:
$ date
If the date is incorrect, then install ntp using your system package manager. After a short time, the date will be properly synchronized.
Useful links
The following resources may be of interest to you: