upstream-mattermost/docs/main/administration-guide/configure/smtp-email.mdx

---
title: "SMTP email setup"
---
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<PlanAvailability slug="all-commercial" />

In a production environment, Mattermost requires SMTP email enabled for email notifications and password resets when using [email-based authentication](/administration-guide/configure/authentication-configuration-settings#enable-sign-in-with-email).

## 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`.

<Tip>

If you don't have an SMTP service you can set one up with [Amazon Simple Email Service (SES)](https://aws.amazon.com/ses/):

1.  Go to [Amazon SES console](https://console.aws.amazon.com/ses) then **SMTP Settings \> Create My SMTP Credentials**.
2.  Copy the `Server Name`, `Port`, `SMTP Username`, and `SMTP Password` values. You'll need these values to configure Mattermost.
3.  From the `Domains` menu, set up and verify a new domain, then enable `Generate DKIM Settings` for the domain. We recommend you set up [Sender Policy Framework](https://en.wikipedia.org/wiki/Sender_Policy_Framework) (SPF) and/or [Domain Keys Identified Mail](https://en.wikipedia.org/wiki/DomainKeys_Identified_Mail) (DKIM) for your email domain.
4.  Choose a sender address like `mattermost@domain.com` and select `Send a Test Email` to verify setup is working correctly.

Alternatively, you can use one of the [services listed below](#sample-smtp-settings), or can set up local `sendmail` by setting **Server Name** `127.0.0.1` with **Port** `25`.

If deploying Mattermost using [Docker](/deployment-guide/server/deploy-containers), the standard docker `172.16.0.0/12` IP range isn't used. Specify the IP range `192.168.0.0/24` to the email service to avoid relay access errors. If using postfix, under `/etc/postfix/main.cf`, specify `mynetworks = 192.168.0.0/24`. This may vary depending on how Mattermost is deployed. Ensure that **Port 25** is open if a firewall is present.

</Tip>

<Note>

[Outlook365 no longer supports Basic Auth](https://support.microsoft.com/en-us/office/pop-imap-and-smtp-settings-for-outlook-com-d088b986-291d-42b8-9564-9c414e2aa040) which is required by Mattermost. We recommend using an alternate Email service like AWS SES (Simple Email Service).

</Note>

## 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](/administration-guide/configure/environment-configuration-settings#smtp) 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.

<Note>

`SMTPPort` and related port settings use string format (e.g., `"465"`) for compatibility with the `host:port` binding format, which requires string concatenation.

</Note>

3.  Select **Save**.
4.  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](#troubleshooting-using-logs) section below for details.

## Sample SMTP settings

<Tabs>
<TabItem value="amazon-ses" label="Amazon SES">

- 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**

</TabItem>
<TabItem value="postfix" label="Postfix">

Make sure Postfix is installed on the same machine as Mattermost.

- Set **SMTP Username** to **(empty)**
- Set **SMTP Password** to **(empty)**
- Set **SMTP Server** to **localhost**
- Set **SMTP Port** to **25**
- Set **Connection Security** to **(empty)**

</TabItem>
<TabItem value="gmail" label="Gmail">

- Set **SMTP Username** to **your_email@gmail.com**
- Set **SMTP Password** to **your_password**
- Set **SMTP Server** to **smtp.gmail.com**
- Set **SMTP Port** to **587**
- Set **Connection Security** to **STARTTLS**

<Warning>

Additional configuration is required in Google to allow SMTP email to relay through their servers. See [SMTP relay: Route outgoing non-Gmail messages through Google](https://support.google.com/a/answer/2956491?hl=en) for the required steps.

</Warning>

</TabItem>
<TabItem value="hotmail" label="Hotmail">

- Set **SMTP Username** to **your_email@hotmail.com**
- Set **SMTP Password** to **your_password**
- Set **SMTP Server** to **smtp-mail.outlook.com**
- Set **SMTP Port** to **587**
- Set **Connection Security** to **STARTTLS**

</TabItem>
<TabItem value="office365-outlook" label="Office365/Outlook">

- Set **SMTP Username** to **your_email@hotmail.com**
- Set **SMTP Password** to **your_password**
- Set **SMTP Server Name** to **smtp.office365.com**
- Set **SMTP Port** to **587**
- Set **Connection Security** to **STARTTLS**

</TabItem>
</Tabs>


## 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`.

``` text
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](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:

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

  Then type something like `HELO <your mail server domain>`. If the command works you should see something like:

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

<Note>

- Telnet isn't included in official Mattermost Docker images, so you either need to use `ping` on those, or install Telnet yourself either directly or by modifying the Dockerfile.
- For further assistance, review the [Troubleshooting forum](https://forum.mattermost.com/c/trouble-shoot/16) for previously reported errors, or [join the Mattermost user community for troubleshooting help](https://mattermost.com/community/).

</Note>