LabKey Server uses an SMTP mail server to send messages from the system, including email to new users when they are given accounts on LabKey. Configuring LabKey Server to connect to the SMTP server is optional; if you don't provide a valid SMTP server, LabKey Server will function normally, except it will not be able to send mail to users.
SMTP Settings
During installation, you will be able to specify an SMTP host, port number, user name, and password, and an address from which automated emails are sent. Values are set in the <LABKEY_HOME>/config/application.properties file.
The SMTP settings available are listed in the template. Uncomment the ones you want to use by removing the leading #:
mail.smtpHost=@@smtpHost@@
mail.smtpPort=@@smtpPort@@
mail.smtpUser=@@smtpUser@@
#mail.smtpFrom=@@smtpFrom@@
#mail.smtpPassword=@@smtpPassword@@
#mail.smtpStartTlsEnable=@@smtpStartTlsEnable@@
#mail.smtpSocketFactoryClass=@@smtpSocketFactoryClass@@
#mail.smtpAuth=@@smtpAuth@@
The basic/minimal set of required properties:
Property | Description |
---|
mail.smtpHost | Set to the name of your organization's SMTP mail server. |
mail.smtpPort | Set to the SMTP port reserved by your mail server; the standard mail port is 25. SMTP servers accepting a secure connection may use port 465 instead. |
mail.smtpUser | Specifies the user account to use to log onto the SMTP server. |
SMTP Authentication and Secure Connections
Many LabKey installations run an SMTP server on the same machine as the LabKey web server, which is configured for anonymous access from the local hot only. Since only local applications can send mail, this ensures some amount of security without the hassle of using a central, authenticated mail server. If you choose instead to use an external authenticated server, you'll need to also uncomment and specify the following properties:
Property | Description |
---|
mail.smtpFrom | This is the full email-address that you are would like to send the mail from. It can be the same as mail.smtpUser, but it doesn't need to be. |
mail.smtpPassword | This is the password for the smtpFrom user. |
mail.smtpstartTlsEnable | When set to "true", configures the connection to use Transport Level Security (TLS). |
mail.smtpSocketFactoryClass | When set to "javax.net.ssl.SSLSocketFactory", configures the connection to use an implementation that supports SSL. |
mail.smtpAuth | When set to "true", forces the connection to attempt to authenticate using the user/password credentials. |
When LabKey Server sends administrative emails, as when new users are added or a user's password is reset, the email is sent with the address of the logged-in user who made the administrative change in the From header. The system also sends emails from the Issue Tracker and Announcements modules, and these you can configure using the
mail.smtpFrom attribute so that the sender is an aliased address. The
mail.smtpFrom attribute should be set to the email address from which you want these emails to appear to the user; this value does not need to correspond to an existing user account. For example, you could set this value to "labkey@mylab.org".
Notes and Alternatives
- If you do not have your own SMTP server available, there are a variety of fee-based mail services and free mail services that may meet your needs. Examples of fee-based ones that have a lot of extra features are PostMarkApp and MailChimp. Free ones may have more limitations, but options like Gmail can also be used.
- If you do not configure an SMTP server for LabKey Server to use to send system emails, you can still add users to the site, but they won't receive an email from the system. You'll see an error indicating that the email could not be sent that includes a link to an HTML version of the email that the system attempted to send. You can copy and send this text to the user directly if you would like them to be able to log into the system.
Troubleshooting
- Begin by double checking that your application.properties file entries for the SMTP parameters (host, user, port, password) are correct. You can validate this by using them to log into the SMTP server directly.
- If you are using Gmail as your email host, you may need to configure your security settings to allow other applications to use it to access the server.
Dumbster for Testing
LabKey Server development source code includes a module named
Dumbster to be used as a dummy SMTP server for testing purposes. See the
testAutomation GitHub repository. It provides a
Mail Record web part, which you can use to test outgoing email without sending actual email. If you are seeing unexpected SMTP configuration values, such as mail.smtp.port set to 53937 when you go to the
Test Email Configuration link on the Admin Console, check the Admin Console's list of deployed modules for the Dumbster module.
If it is present, you may need to disable the capture of email via the Mail Record web part to enable SMTP to send email. Learn more here:
Related Topics