Configure the SMTP Server


Before email templates and other email features may be utilized, you must first enable and configure an SMTP server.

FusionAuth doesn’t come bundled with an SMTP server, but expects one to be configured to enable all email based functionality (“bring your own SMTP server” or BYOSS). This design choice allows you to:

  • use whatever email sending service you’d like (some are listed below, but FusionAuth will work with any providers with an SMTP API)
  • send email from your own IPs with reputation you control
  • skip configuring an SMTP server if you are not sending email from FusionAuth

To enable and configure the SMTP server navigate to Tenants -> Email.

Email Settings

Enable email by clicking on the Enabled toggle, and save your settings once you have completed your configuration.

SMTP Settings

HostDefaults to localhost

The hostname of the SMTP server. This will be provided by your SMTP provider.

PortDefaults to 25

The port of the SMTP server. This will be provided by your SMTP provider. Ports 25, 465 and 587 are the well known ports used by SMTP, it is possible your provider will utilize a different port.

In most cases you will be using TLS to connect to your SMTP server, and the port will generally be 587 or 465.


The username used to authenticate to the SMTP server. This will be provided by your SMTP provider.

Change password

When enabled, you may modify the SMTP password, when the Password field is not displayed the current password will not be modified.


The new password to use for the outgoing SMTP mail server authentication. This field is only required when Change password is checked.


The security type when using an SSL connection to the SMTP server. This value should be provided by your SMTP provider.

Generally speaking, if using port 25 you will select None, if using port of 465 you will select SSL and if using port 587 you will select TLS. It is possible your provider will be different, follow your providers instruction.

  • None
  • SSL
  • TLS
Default from address

The default From Address used in sending emails when a from address is not provided for an individual email template. This is an email address (i.e.

Default from name

The default From Name used in sending emails when a from name is not provided on an individual email template. This is the display name part of the email address (i.e. Jared Dunn <>).

Additional headersAvailable since 1.32.0

One or more line separated SMTP headers to be added to each outgoing email. The header name and value should be separated by an equals sign. (i.e. X-SES-CONFIGURATION-SET=Value).

Debug enabledAvailable since 1.37.0

When enabled, SMTP and JavaMail debug information will be output to the Event Log.

SMTP Providers

This information is for starting guidance only. FusionAuth connects seamlessly with many different email providers. A deep exploration of email best practices and providers is outside the scope of this document.


SendGrid is a commonly used SMTP provider and integrates well with FusionAuth. To setup SendGrid, follow these instructions.

Other resources related to SendGrid are linked below:


Using dedicated IP addresses for any SendGrid account will build email reputation over time (improving email deliverability). And lastly, to control spoofing, phishing, and spam, it is recommended to set up SPF and DKIM records for the primary email domain (such as Emails should also be sent from an address such as


Gmail is a commonly used SMTP service. Gmail is not recommended for production use, since it has a number of limits. However, it can be useful to test email functionality.

For Gmail, use application passwords, otherwise you may get a generic Unable to send email via JavaMail / Prime Messaging Exception error.