Enabling SMTP

Overview

Polarity can connect to an existing SMTP server to send email notifications to Polarity users. Emails are sent for the following purposes:

Email	Description
Account Creation	When a new local account is created, an account creation email is sent to the new account which can include an auto generated login password.
Upvote Notification	If enabled by the user, the user will receive an email anytime an annotation they applied is upvoted.
Comment Notification	If enabled by the user, the user will receive an email when a comment is made on an annotation they applied or previously commented on.
Channel Notification	If enabled by the user, the user will receive an email anytime they gain access to a new channel.
Integration Notification	If enabled by the user, the user will receive an email when they gain access to a new integration.

SMTP can be enabled on the Polarity server by logging in via the web interface using an account with admin privileges. After navigating to the "Advanced Settings" page, in the left navigation panel, select "Server Configuration" and then along the top of the page select "SMTP".

If this is your first time configuring SMTP, click on the Edit button and fill in the required options. After configuring the required options be sure to click on the Enabled toggle to turn on the SMTP mailing service.

Configuration

The following is a list of options that can be configured:

Primary SMTP Options

Host

The fully qualified domain name of the SMTP server. As an example, this might be smtp.mycompany.corp.

Port number

The port number for your SMTP server. The standard port is 25 or for secure SMTP, 587.

Username

The username to use when authenticating to the SMTP server.

Password

The password for the provided Username option above.

For unauthenticated SMTP, leave the Username and Password fields empty.

From email address

Address you want notification emails to be sent from.

Connection Security

Choose one of the following options for connection security. The most common option is TLS particularly if your SMTP server is running over port 587. If your SMTP server is running over port 25 you may need to set this to None.

• None

• SSL

• TLS

Additional Options

Timeout Duration

The amount of time in milliseconds the Polarity Server will wait while attempting to connect to the SMTP server. This value defaults to 5,000 and does not typically need to be changed.

Domain

This value will default to the hostname of the Polarity Server and does not typically need to be changed.

Authentication

A list of preferred authentication methods to use. The default value is CRAM-MD5, LOGIN, PLAIN, and XOAUTH2. This value does not typically need to be changed.

Testing

You can test whether the Polarity Server is successfully able to send an email by using the Test SMTP Settings button at the bottom of the SMTP configuration page

After clicking on the button, if an email message was successfully sent, you will see a message that says "Successfully sent mail". The email itself will be sent to the email address for the account you are currently logged in as. Check to ensure that you received the email to confirm that SMTP settings are properly configured.

If the Test SMTP settings button is disabled ensure that you have enabled SMTP by clicking on the "Enabled" toggle within the configuration window.

Troubleshooting

Test SMTP settings successful but no email is received

If the Test SMTP settings button returned a success message but you did not receive an email please double check the following:

1. Ensure the email did not go to your spam folder

2. Ensure you are checking the right email address. The email will be sent to the email address associated with the account that you are logged in with when you click on the Test SMTP settings button. You can double check your email address by navigating to the "My Profile" page under "Advanced Settings".

3. Check your SMTP server logs to see if the email is being blocked. Once the Polarity server successfully authenticates with the SMTP server it cannot know if the email was successfully delivered and so you will need to check the SMTP server logs for additional troubleshooting information.

Error with SMTP Status Code Returned

If you receive back an SMTP status code you can check the meaning of the code using the following reference: https://en.wikipedia.org/wiki/List_of_SMTP_server_return_codes

Common codes include:

• 535 5.7.8 indicates an invalid username of password

• 421 service is not available

ENOTFOUND getaddrinfo Error

This error message typically means the SMTP Host value is incorrect.

ERR_SSL_WRONG_VERSION_NUMBER

This error typically means an incorrect Authentication option was chosen. If you selected SSL as your Authentication option please try changing it to TLS.

Failed to perform status check

This generic error message can mean the SMTP port is incorrect.

Other Failure Messages

If the SMTP host and authentication credentials are correct, the most common reason mail cannot be sent is that the SMTP server is configured to only allow mail sending from either specific email addresses, specific domains, or specific server addresses.

In some cases, changing the From email address or Domain to an allowed address or domain can resolve the issue.

In other cases, you will need to check with your SMTP administrators to see if the Polarity server needs to be added to an allow list to enable SMTP.