With Open edX Ginkgo, integrating an SMTP email account like Google’s Gmail is as simple as setting a few parameter values in the four JSON configuration files for the LMS and Course Management Studio, each of which are located in /edx/app/edxapp/. Get SMTP email working on your Open edX instance in less than an hour with this step-by-step how-to guide.
Summary
The native build of Open edX relies on a simple email generator utility that comes with Ubuntu 16.04. While this technically works, the messages that it generates for new user activations, password reset instructions, and welcome messages are generally universally flagged as spam by common email management client applications like MS Outlook, Mac Mail and so on. Fortunately however, the architects of Open edX have made it easy for you to integrate an SMTP email account to your instance. Take note that the configuration procedure has been simplified over time, but much of the online documentation that I find has not kept pace with these changes, and this can make it appear as though getting SMTP email working is more complicated that it really is.
We’ll integrate a Google Gmail account in this tutorial, but you can use just about any other SMTP mail provider and these instructions will still be valid. Google’s Gmail email service is designed to be accessed by third party applications. The email management software that you use on your Desktop and mobile devices for example are third-party apps that provide the means to quickly connect and synchronize your local email message storage system to Gmail’s email services.
SMTP is a standardized protocol that Gmail and many other email providers use to allow third party applications to integrate and synchronize with the central email servers of the service provider. Apple and Android both provide really good out-of-the-box mobile apps for email that let you connect to a Gmail account; usually requiring no more than a user name and password. Open edX uses the same approach, but without the nice GUI interface.
Setup Procedure
1. Configure Your Gmail Account
There is one small but important change that you’ll need to make to your default Gmail account settings in order for Gmail to allow Open edX to connect. After logging in to your Gmail account from a web browser, navigate to https://myaccount.google.com/lesssecureapps to change the setting for “Allow less secure apps” to “On”.
2. Edit /edx/app/edxapp/lms.auth.json
lms.auth.json contains authorization credentials for the various subsystems that support the Learning Management System (LMS) application; email username and password being two such credentials. Each time the LMS attempts to send an email message it refers to the username and password from this file to establish a connection and send the message using the Gmail SMTP email service.
Pro Tip: Keep a backup copy of the original versions of each of the four JSON files in /edx/app/edxapp. JSON syntax is as rigid as it is unforgiving, and any syntax errors in these four JSON files will prevent your Open edX platform from restarting.
3. Edit /edx/app/edxapp/cms.auth.json
cms.auth.json contains authorization credentials for the various subsystems that support the Course Management Studio (CMS) application. The structure of this file is similar, but not identical to that of lms.auth.json from the previous step. You’ll also add your Gmail username and password to this file.
4. Edit /edx/app/edxapp/lms.env.json
lms.env.json contains application parameters and option values for the LMS. You’ll do two things in this file. First, you’ll add your Google Gmail SMTP settings, and second, you’ll set your gmail email address in various locations in the file.
Note that you’ll find other parameters in this file with an “EMAIL_” prefix. If I don’t mention them in this article then they’re not required for setting up SMTP email.