Skip to main content

SMTP email setup

In a production environment, Mattermost requires SMTP email enabled for email notifications and password resets when using email-based authentication.

Set up an SMTP email service​

Any SMTP email service can be used. You need a copy of the following information: Server Name, Port, SMTP Username, and SMTP Password.

Configure SMTP settings​

  1. In Mattermost go to System Console > Authentication > Email, and set Allow Sign Up With Email to true.
  2. In the System Console, go to Notifications > Email and configure Mattermost for your SMTP service. See the SMTP configuration documentation for details.
  • Set Send Email Notifications to true.
  • Set the Notification Display Name for the account sending notifications.
  • Set Notification Email Address for the email address used to send notifications.
  • Enter the SMTP Username, SMTP Password, SMTP Server, and SMTP Port you copied from initial setup.
  • We recommend setting Connection Security: to TLS (Recommended) to encrypt communication between Mattermost and your SMTP service.
  1. Select Save.
  2. Under Connection Security, select Test Connection. Mattermost will confirm whether a connection to the SMTP service is successful by sending you an email. If the test fails, Mattermost will provide details about why it failed in the System Console. See the check Mattermost logs section below for details.

Sample SMTP settings​

  • Set SMTP Username to [YOUR_SMTP_USERNAME]
  • Set SMTP Password to [YOUR_SMTP_PASSWORD]
  • Set SMTP Server to email-smtp.us-east-1.amazonaws.com
  • Set SMTP Port to 465
  • Set Connection Security to TLS

Troubleshooting SMTP​

TLS/STARTTLS requirements​

If you fill in SMTP Username and SMTP Password then you must set Connection Security to TLS or to STARTTLS

Troubleshooting using logs​

If you have issues with your SMTP install, from your Mattermost team site go to System Console > Logs to look for error messages related to your setup. You can do a search for the error code to narrow down the issue. Sometimes ISPs require nuanced setups for SMTP and error codes can hint at how to make the proper adjustments.

For example, if System Console > Logs displays the following error, search for 554 5.7.1 error and Client host rejected: Access denied.

Connection unsuccessful: Failed to add to email address - 554 5.7.1 <unknown[IP-ADDRESS]>: Client host rejected: Access denied

Checking your Notifications settings​

If an SMTP connection test in the System Console for a self-hosted Mattermost deployment fails with the message Connection unsuccessful: Failed to set the to address: 550 5.7.27 [test@example.com](mailto:test@example.com), go to System Console > Site Configuration > Notifications to verify that notification settings are configured correctly, including Notification Display Name, Notification From Address, Support Email Address, and Notification Reply-To Address. Cloud administrators can't manage Notification From Address or Notification Reply-To Address.

Checking your SMTP server is reachable​

  • Attempt to Telnet to the email service to make sure the server is reachable. For additional information, visit https://learn.microsoft.com/en-us/exchange/mail-flow/test-smtp-with-telnet?view=exchserver-2019. If you're using an earlier version than Exchange Server 2019, select your version from the left-hand navigation menu.

  • You must run the following commands from the same machine or virtual instance where mattermost/bin/mattermost is located.

  • Telnet to the email server with telnet mail.example.com 25. If the command works you should see something like:

    Trying 24.121.12.143...
    Connected to mail.example.com.
    220 mail.example.com NO UCE ESMTP

    Then type something like HELO &lt;your mail server domain&gt;. If the command works you should see something like:

    250-mail.example.com NO UCE
    250-STARTTLS
    250-PIPELINING
    250 8BITMIME