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.

For more information about SMTP, see this guide. The following 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 cliks 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:

failed SMTP Test in WordPress

Error message when resetting password in Wordpress

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, see this guide.
  • 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 in ports 25 or 465. 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:

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 (if you are using a Windows server, use this guide).
  • 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 ports 25, 465 or 587. To learn how to use a VPN to bypass these restrictions or 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 "How to configure outbound mail settings" section in the application documentation page. For example, this is the documentation page for WordPress.

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.

The following resources may be of interest to you:

aws

Bitnami Documentation