Using Gmail as your XNAT SMTP Server

This is most useful for development instances of XNAT, such as one running on a Vagrant VM, for users who don't have ready access to an institutional SMTP server for managing notifications.

Why Use Gmail as an SMTP Server?

XNAT has several functions where it needs to send emails to users -- particularly when notifying users of project invitations, or when data processing commands have been completed. However, XNAT does not ship with an SMTP server. In some cases, you can use an email server provided by your enterprise or institution. If not, it is possible to use a valid Gmail account for this purpose.

Note: This is more difficult than it used to be. Google has become more security-conscious over time, and has made it more difficult to use this service. These instructions will attempt to point you in the right direction.

Step 1: Configure Your XNAT

In your XNAT, go to Administer > Site Administration in the top navigation, then click on the Email Server tab in the admin panel. Then, configure your SMTP mail server like this, using your Gmail user credentials.

Step 2: Adjust Your Google Account Permissions

Your Google Account may have a security setting that prevents "less secure apps" from using services associated with your account. You can change this setting here: https://myaccount.google.com/lesssecureapps.

To enable your XNAT instance to use your Gmail credentials and route email through their SMTP server, set "Allow less secure apps: ON".

Note: Google will silently and automatically adjust this setting back to its default if you are not using the SMTP server for a certain period of time. You may also receive a security warning notification after setting this feature.

Step 3: Send a Test Email

Return to your XNAT and go to Administer > Send Email in the top navigation. Select a user that has a valid email account. (If none exist, you can remedy that in the Administer > Users control panel.) Click the "To" checkbox next to that user's name and send a test email. This will either work properly, or give you an error page with a Server Error (500) report. If the latter happens, you can look in your server logs (turbine.log most commonly has the problem), which are located in /data/xnat/home/logs.

If Google Mail is still rejecting your authentication or your ability to send mail, here's how to troubleshot:

Step 4 (If Needed): Install Postfix on your Virtual Machine

An XNAT Virtual Machine runs on a Linux Ubuntu server, which can be upgraded with the optional PostFix service. Instructions on how to set this up are fairly straightforward, and can be found here: https://kifarunix.com/configure-postfix-to-use-gmail-smtp-on-ubuntu-18-04

Note: You may need to run "apt-get update" before performing the steps in that Postfix tutorial

After completing the PostFix tutorial, try sending another test email.