Overview

The platform supports custom email integrations, which allows you to leverage your own email system for sending and receiving emails.

Configuring custom email

By default, all emails sent and received via the platform are routed through the platform's email server.

To reduce the chance of your emails being flagged as spam, it's better that all emails sent and received through the platform are routed through your own organization's email server.

1. First, create an email account for your organization that will be used specifically for email integration with the platform.
   
1. It is recommended to name this account "messages". For example, if your organization's domain is myorganization.com, create an account called messages@myorganization.com for the integration.
   
2. The email used for the email integration should not be a personal email address or used for any other communication as the platform can delete emails in that account as part of the email syncing process.
   
3. Additionally, contact your email provider to learn about any email volume limitations to prevent overloading when sending large numbers of emails.
   

To begin configuring custom email, you must first install the Custom email app. To install the app:

1. Click Admin from the primary navigation menu.
   
2. Click App center from the fly-out menu.
   
3. Install the Custom email app in the Email section.
   
4. After installing the app, click the Configure  icon on the Custom email tile. 
   

The email Configure page displays.

1. Select your email provider.
   

Configuration settings display for Outgoing emails and Incoming emails.

1. Complete the form based on your email system. Additional information about the fields below:
   
1. User: The user name of the email account without the domain. In this example, it would be "messages".
   
2. Password: The password for the email account.
   
3. Domain: The domain of the email account.
   
4. SMTP server: The address of your SMTP server.
   
5. SMTP port: The port of your SMTP server.
   
6. SMTP authentication: The kind of authentication your SMTP server requires.
   
7. Use TLS for SMTP?: Enable if your SMTP server requires TLS.
   
8. POP3 server: The address of your POP3 server.
   
9. POP3 port: The port of your POP3 server.
   
10. POP3 polling: The number of minutes for your POP3 polling.
    
2. Click Save.

1. Click Send test message to test your configuration settings. This will send an email via your SMTP server. If the configuration is correct, the message will be sent to your email account within a few seconds.
   
2. Click Edit if you would like to edit your email integration settings.
   
3. Click Disable to disable your email integration settings.
   

AWS-SES integration 

The AWS-SES integration allows you to use AWS-SES to send emails, and a POP3 server to receive emails. 

1. Click Admin from the primary navigation menu.
   
2. Click Email from the fly-out menu.
   
3. Click the Configure tab.
   
4. Click AWS-SES.

In the Incoming emails section, the Different POP3 account? option is selected by default. 

1. Complete the Incoming emails section with your POP3 email retrieval protocol information.
   
2. Click Save.

Microsoft 365 email integration

Enabling SMTP

1. To enable SMTP with Microsoft 365, please follow the directions provided here.
   

Configuring Email

Once SMTP is enabled with your Microsoft 365 account, you can set up the integration:

1. Click Admin from the primary navigation menu.
   
2. Click Email from the fly-out menu.
   

The Email page displays.

1. Click the Configure tab.
   
2. Click Office 365.
   

In the Outgoing emails section, enter your Office 365 account credentials:

1. User: The user name before @yourOfficeDomain.com.
2. Password: Your Microsoft account password.
3. Domain: yourdomain.com.
   

Scroll to the bottom of the page:

1. Click Save.
   

After saving your credentials:

1. Click Edit on the Configure tab.
   

In the Incoming emails section:

1. Click Configure OAuth 2.0 for POP3.
   

The Configure authentication page displays.

1. Keep the Configure authentication page open, as you will need the Redirect URI information when registering the application with Microsoft Entra ID in another browser window or tab.
   

Microsoft Entra ID

In order to obtain the OAuth 2.0 credentials for incoming email, you have to create an application with Microsoft Entra ID. To create the application:

1. Log into Microsoft Azure with your Office 365 account credentials.
   

The Welcome to Azure page displays.

1. Click View in the Manage Microsoft Entra ID section. 
   

In the left menu:

1. Click App registrations.
   

The App registrations page displays.

1. Click + New registration.
   

The Register an application page displays. 

On the App registrations page, the application name and details display.

1. Copy the Application (client) ID and Directory (tenant) ID for future use.

From the left navigation menu:

1. Click Certificates & secrets.
   

The Certificates & secrets page displays.

1. Click + New client secret.
   

The Add a client secret pop-up displays.

1. Enter a Description.
   
2. Click Add.
   

A Client secret Value and Secret ID are created.

1. Click the Copy  icon to copy the Value.
   
1. The newly created Value is the Client secret, which you will use in the learning platform to authenticate. 
   

Configuration Page

Now that you have a Microsoft Entra ID application and authentication information, you can complete the email configuration.

1. Return to the Configure authentication screen in your platform. 

Next, you will configure OAuth 2.0 POP and authenticate your email credentials. To ensure you are asked to authenticate in a new window, you will need a new session.

It is recommended that you open a new browser window in Incognito mode to create a new session before proceeding with the following steps.

1. Click Admin from the primary navigation menu.
   
2. Click Email from the fly-out menu.
   
3. Click the Configure tab.
   
4. Click Edit.
5. Click Configure OAuth 2.0 for POP3 in the Incoming Emails section.

1. Click Get access token.
   

Because you have accessed the page with a new session, you will be prompted to pick an account.

1. Log in with your Office 365 account (the account used for the integration).
   

Accept the requested permissions.

The page refreshes and the access token and expiration date are available. Your Microsoft 365 email has been authenticated.

Gmail email integration

To set up a Gmail email integration, first, ensure you are using App passwords:  

1. You must use App passwords with Gmail to provide the platform with permission to access your Google account. More information can be found here. 
   
1. Note that in order to use App passwords, you must enable 2-Step Verification on your account. To learn more, visit the 2-Step Verification documentation from Google.

To set up an Gmail email integration:

1. Click Admin from the primary navigation menu.
   
2. Click Email from the fly-out menu.
   
3. Click the Configure tab.
   
4. Click Google.

The Google configuration settings display.

1. No changes are needed for the default selections in the Outgoing emails section.
   
2. In the Incoming emails section:
   
1. POP3 user: Enter your gmail account name (the name before the @).
   
2. POP3 domain: Enter gmail.com.
   
3. Click Save.

After saving, you must configure Oath 2.0 for POP3. On the Configure tab:

1. Click Edit.
   

The edit configuration settings page displays.

1. Click Configure OAuth2.0 for POP3 in the Incoming emails section.
   

The Configure authentication page displays.

1. Keep the Configure authentication page open, as you will need the Redirect URI information when setting up the application with Gmail in another browser window or tab.
   

Google Cloud Console

Next, you will set up a new project with Google Cloud Console. To begin:

1. Log-in to the Gmail account you will be using to set up the integration.
   
2. Then, access the Google Cloud Console.
   
3. Click Select a project on the top menu.
   
4. Click New Project.
   
5. Name your new project. In this example, the organization will be named Google POP. 
   
6. Click Create.
   
7. Select your new project.

After selecting the project, enable the Gmail API:

1. Click the Google Cloud  navigation menu in the upper left corner.
   
2. Click APIs & Services.
   
3. Click Library.
   
4. Click Gmail API.
   
5. Click Enable.
   

Next, you must configure the OAuth consent screen.

1. Click the Google Cloud  navigation menu in the upper left corner.
   
2. Click APIs & Services.
   
3. Click OAuth Consent Screen.
   
4. Click Get Started.
   

The Project configuration page displays.

1. Create an App name.
   
2. Add a User support email, for users that contact you with questions about their consent.
   
3. Click Next.
   
4. Select External in the Audience section.
   
5. Click Next.
   
6. Add a Contact email address so Google can notify you about any changes to your project.
   
7. Agree to the Google API Services: User Data Policy.
   
8. Click Create.

Next, you will create credentials for the project.

1. Click the Google Cloud  navigation menu in the upper left corner.
   
2. Click APIs & Services.
   
3. Click Credentials.
   
4. Click Create credentials.
   
5. Click OAuth client ID from the drop-down menu.
   

The Create Oauth client ID page displays.

1. Application type: Select Web application.
   
2. Name: Enter a name for your OAuth 2.0 client. Platform client is used in the example below.
   
3. Click Add URI in the Authorized redirect URIs section.
   
4. Enter the Redirect URI
   
1. You can find the Redrect URI on the Configure authentication page in your learning platform.
   
5. Click Create.

The OAuth client created pop-up displays.

1. Copy the Client ID and Client secret, as both will be needed when setting up the integration in your learning platform.
   

Next, you will update your Data access scopes. 

1. Click Credentials on the left menu.
   
2. Click the OAuth 2.0 Client ID you just created (Platform client was the example used in the previous screenshots).
   
3. Click Data Access on the left menu.
   
4. Click Add or Remove Scopes.
   
5. Use the search filter to locate the https://mail.google.com/ scope.
   
6. Select the Gmail API checkbox.
   
7. Click Update.

Now, you will add your integration email.

1. Click Audience on the left menu.
   
2. Click + Add Users in the Test users section.
   
3. Add the e-mail account you have been using for the integration.
   
4. Click Save.
   

Enable POP in Gmail

To enable POP in Gmail:

1. Access the Gmail account you are using to set up the integration.
   
2. Click the Settings icon in the upper right corner of your Gmail screen.
   
3. Click See all settings.
   
4. Click the Forwarding and POP/IMAP tab.
   
5. You can select either Enable POP for all mail or Enable POP for mail that arrives from now on, depending on your preference.
   
6. Click Save Changes.

Configuration Page

Now that you have Gmail client information, you can complete the email configuration.

1. Return to the Configure authentication screen in your platform. If you closed your browser window, to access the page again:
   
1. Click Admin from the primary navigation menu.
   
2. Click Email from the fly-out menu.
   
3. Click the Configure tab.
   
4. Click Edit.
   
2. Click the Configure OAuth 2.0 for POP3 button in the Incoming emails section.
   

The Configure authentication page displays. Complete the fields using the following information:

1. Authorization URL: https://accounts.google.com/o/oauth2/auth?access_type=offline&prompt=consent
   
2. Token URL: https://oauth2.googleapis.com/token
   
3. Scope: https://mail.google.com/
   
4. Client ID: Enter the Client ID you saved from the OAuth Client created pop-up in the Google Cloud Console. 
   
5. Client secret: Enter the Client secret you saved from the OAuth Client created pop-up in the Google Cloud Console. 
   
6. Click Save.

To complete the authentication, you must get an access token. To get the access token:

1. Click Configure OAuth 2.0 for POP3 in the Incoming Emails section.
   
2. Click Get access token.
   

An authentication window from Google will display.

1. Select the Google account used for the integration.
   
2. If prompted, login to the account.
   
3. Click Continue to verify that you trust the learning platform and provide access for the platform to read, compose, send, and delete email from Gmail.

Once authentication has been granted, the Configure authentication page refreshes and the access token and expiration date display.

1. Click Save to save your updates.
   

Your Gmail account has been authenticated.

Common email errors

Below are common errors you may encounter when integrating your email account with the platform, along with steps to troubleshoot them.