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
- Note that if you are running Windows and you don't have an SMTP server available, you can set one up on your local computer.
- 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.
- If you are running on Windows and you don't have a mail server available, you can configure the SMTP service. This service is included with Internet Information Server to act as your local SMTP server. Follow these steps:
- From the Start menu, navigate to Control Panel | Add or Remove Programs, and click the Add/Remove Windows Components button on the left toolbar.
- Install Internet Information Services (IIS).
- From Start | Programs | Administrative Tools, open the Windows Services utility, select World Wide Web Publishing (the name for the IIS service), display the properties for the service, stop the service if it is running, and set it to start manually.
- From Start | Programs | Administrative Tools, open the Internet Information Services utility.
- Navigate to the Default SMTP Virtual Server on the local computer and display its properties.
- Navigate to the Access tab, click Relay, and add the address for the local machine (127.0.0.1) to the list of computers which may relay through the virtual server.
Troubleshoot SMTP
- Begin by double checking that your labkey.xml 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 own email host, you may need to configure your gmail security settings to allow other applications to use it to access the server.
- 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
