SMTP settings

Simple Mail Transfer Protocol (SMTP) settings are your outgoing email server settings. This particular protocol only works for outgoing messages and is used with various portal features that send emails from the portal, such as  sending records by email, password recovery, and email notifications about changes on records a member is subscribed to.

 

 

To configure SMTP settings in the portal backoffice

1. In the backoffice, go to Media > Site settings.
2. On the General tab, under SMTP settings, select Add content to create a new set of settings, or edit existing settings.
3. Select the authentication method:
   1. Legacy password-based authentication
   2. OAuth 2.0 authentication (recommended)
4. Fill in the fields as described below.
   1. If you selected Legacy password-based authentication:
      1. Enabled - Specifies whether this set of SMTP settings will be enabled. If you have multiple SMTP setting sets enabled, the first set of settings will be used.
      2. Email category - Specifies the category of emails that this SMTP setting set will be used for.
         The first found enabled SMTP setting set for each email category will be used. We recommend configuring a separate set of settings for each category. If the portal cannot find separate settings for the Notifications or Administration category, the General category will be used.
         1. Administration: For administration emails only.
         2. General: For all portal emails except administration- and notification-related emails.
         3. Notifications: For email notifications only.
      3. Network host - Specifies the actual outgoing email server hostname that is an individual one for each provider. For example, smtp-mail.outlook.com; smtp.gmail.com.
      4. Username - Specifies the email address from which emails will be sent.
      5. Email - Specifies the email address that will be used to send emails from.
      6. Password - Specifies the password of the email address specifies in the Username setting.
      7. Port - Specifies the port through which emails will be sent. Port 587 is recommended for secure connection.
      8. Enable SSL - Specifies whether the SMTP connection will be secured with SSL.
      9. Default credentials - Specifies whether the default credentials (username and password) will be used instead of the credentials specifies in this settings set.
      10. Redirect to report email - Specifies whether all emails sent by the portal will be redirected to the email(s) specifies in the Report emails setting. Redirecting emails is useful for testing purposes.
      11. Report emails - Specifies email(s) to which all emails sent by the portal will be redirected if the Redirect to report emails setting is enabled. You can set up multiple report emails.
          1. Email – Specifies the email to which all emails sent by the portal will be redirected if the Redirect to report emails setting is enabled. 
          2. Enabled – Specifies whether this report is enabled. Use this switch to temporarily disable a report email without having to remove the settings.
             
   2. If you selected OAuth 2.0 authentication
      1. Enabled - Specifies whether this set of SMTP settings will be enabled. If you have multiple SMTP setting sets enabled, the first set of settings will be used.
      2. Email category - Specifies the category of emails that this SMTP setting set will be used for.
         The first found enabled SMTP setting set for each email category will be used. We recommend configuring a separate set of settings for each category. If the portal cannot find separate settings for the Notifications or Administration category, the General category will be used.
         1. Administration: For administration emails only.
         2. General: For all portal emails except administration- and notification-related emails.
         3. Notifications: For email notifications only.
      3. Identity provider - Specifies the service that provides OAuth 2.0 authentication services. Select Google or Microsoft Entra ID. A custom identity provider can be added as part of customization.
      4. Network host - Specifies the actual outgoing email server hostname that is an individual one for each provider. For example, smtp-mail.outlook.com; smtp.gmail.com.
         1. For Microsoft Entra ID: enter smtp-hve.office365.com (used for big volumes of data) or smtp-hve.office365.com 
      5. Token issue method - Specifies the method that defines the flow of issuing a token by the identity provider:
         1. Authorization code - For issuing a tokem, an autherization code is sued. If this method is used, you will need to ontain the refresh token in the Refresh token setting using the Authorize action next to it. 
         2. Client credentials - The client credentials are used to issue a token.
         3. Password - A password is used to issue a token. If this method is used, in the Password setting, you will need to specify the password of the account that was used for configuring the corresponding identity provider.
            1. For Microsoft Entra ID: use the Autherization code (preferred) or Password method.
            2. For Google: only the Autherization code method is supported
      6. Username - Specifies the email address from which emails will be sent.
      7. Email - Specifies the email address that will be used to send emails from.
      8. Password - Specifies the password of the email address specifies in the Username setting. With OAuth 2.0 authentication, this setting is filled in only when the Token issue method setting is set to Password.
      9. Port - Specifies the port through which emails will be sent. Port 587 is recommended for secure connection.
         1. For Microsoft Entra ID: enter 465 (for SSL) or 587 (for STARTTLS, which is preferred for Microsoft Exchange)
         2. For Google: enter 465 (for SSL, preferred for Google) or 587 (for STARTTLS)
      10. Default credentials - Specifies whether the default credentials (username and password) will be used instead of the credentials specifies in this settings set.
      11. Redirect to report email - Specifies whether all emails sent by the portal will be redirected to the email(s) specifies in the Report emails setting. Redirecting emails is useful for testing purposes.
      12. Report emails - Specifies email(s) to which all emails sent by the portal will be redirected if the Redirect to report emails setting is enabled. You can set up multiple report emails.
          1. Email – Specifies the email to which all emails sent by the portal will be redirected if the Redirect to report emails setting is enabled. 
          2. Enabled – Specifies whether this report is enabled. Use this switch to temporarily disable a report email without having to remove the settings.
      13. Client ID - Specifies the client ID that was obtained for this portal application on the identity provider site.
      14. Client secret - Specifies the client secret that was obtained for this portal application on the identity provider site.
      15. Refresh token - Specifies the refresh token. Refresh tokens are issued to the client by the authorization server and are used to obtain a new access token when the current access token becomes invalid or expires, or to obtain additional access tokens with identical or narrower scope (access tokens may have a shorter lifetime and fewer permissions than authorized by the resource owner).
          This setting is used when the Token issue method setting is set to Authorization code. To get a refresh token from the identity provider, after you have set up the Client ID, Client secret and (in case of Microsoft Entra ID), the Tenant ID settings, select the Authorize action and authorize a Microsoft/Google account with the corresponding identity provider. The account must have the appropriate permissions to send emails. Once you sign in, follow the instructions on screen and, if asked, grant permissions that the identity provider requests. As a result, the refresh token is issued by the identity provider and automatically filled in this setting.
           
      16. Provider-specific settings - Specifies the additional settings that may be required for the chosen identity provider.
          1. External service name - Specifies the name of the setting for which the value must be specified in the Value setting.
          2. Value - Specifies the value for the selected setting.
          3. Comment - Specifies a description of the external service. You can use this field to add a note about the setting if necessary.

             Note In provider-specific settings, you need to configure the following: For the Microsoft Entra ID identity provider: Tenant ID (required) Scope (optional) - defines the permissions (what can be accessed) For the Google provider: Scope (optional)  Also, for some identity providers, you may need to configure Access token URL template (not necessary for Microsoft Entra ID or Google). This URL template may include variables, such as the variable for tenant ID. For example: https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token

5. Optionally, create an alternative set of of SMTP settings. Only one set of SMTP settings can be enabled at a time; if you have multiple SMTP setting sets enabled, the first set of settings will be used. However, you can have separate settings for each email category.
6. In the backoffice, select Settings > More > Reload Application for changes in the SMTP settings to take effect.

Setting up identity providers for SMTP

Before configuring OAuth 2.0 authentication in the SMTP settings of the portal backoffice, you must set up an identity provider that you are going to use for your SMTP authentication on their site. For OAuth 2.0 authentication SMTP configuration on the portal side, you will need certain values, such as the client ID, client secret, and tenant ID that you can obtain while configuring the identity providers, therefore, make sure you save them.

Configuring Microsoft Entra ID for SMTP

To configure Microsoft Entra ID for SMTP authentication:

1. Go to App registrations in the Azure portal. If needed, sign in with a Microsoft account that has administrator permissions.

   Note If you already have a registered app for your portal (which was created and configured, for example, for the SSO functionality), you don't need to create another app registration. In this case, skip the next step, and then expand the existing app configuration with additional setting that are required for SMTP authentication.

2. Create a new app registration:
   1. Select New registration, then enter an application name.
      

      Note Only Microsoft accounts with administrator permissions can create new app registrations.

   2. In the Register an application window, enter the name of the application (leave the Redirect URI section empty for now), and then select Register.
      
3. In the App registrations window, open the registered app by selecting its name in the app list.
   
4. Add a client secret. If your portal app has already been registered before with a client secret added, you can skip this step (in this case, contact your administrator to get the client secret value because you will need it later when configuring SMTP in the Xpand Portal backoffice).
   1. In the Overview section, select Add a certificate or secret next to Client credentials.
       
   2. In the Certificates & secrets window that opens, under Client secrets, select New client secret.
      
   3. In the Add a client secret window, fill in the required fields, and then select Add.
      
   4. Copy the client secret from the Value field as you will need it for further configuration of the SSO settings on Xpand Portal.
      

      Note Make sure to copy the client secret from the Value field as you will not be able to access it in future.

5. In the navigation pane on the left, select Overview and copy the client ID from the Application (Client) ID field as well as tenant ID from the Directory (tenant) ID field as you will need them for further configuration of the SMTP settings in the Xpand Portal backoffice.
   
6. Select Add a Redirect URI next to Redirect URIs.
   
7. In the Authentication window that opens, under Platform configurations, select Add a platform.
   
8. In the Configure platforms window that appears, select Web. 
   
9. In the Configure Web window, fill in the Redirect URIs field with a URI that matches your portal's authorization endpoint, and then select Configure.

   https://[yourportaldomain]/security/Oauth/2.0/Oauth/HandleRedirectOAuth
   
   where [yourportaldomain] is the domain where your Xpand Portal solution is deployed.

   

10. Select Save to save the changes.
11. On the API Permissions page, add the required Microsoft Graph and Office 365 Exchange permissions (these permissions are used to obtain the correct token):
    1. To add Microsoft Graph permissions:
       1. On the API Permissions page, on the Microsoft APIs tab, select Microsoft Graph.
          
       2. Select Delegated permissions.
       3. Search for a permission by its name. You need to add the following Microsoft Graph permissions:
          • email (delegated)
          • offline_access (delegated)
          • openid (delegated)
          • SMTP.Send (delegated)
            
            
       4. Select a permission, and then select Add permissions. Added Office 365 Exchange Online permissions look as follows:
          
    2. To add Office 365 Exchange Online permissions:
       1. On the API Permissions page, on the APIs my organization uses tab, search for, and then select Office 365 Exchange Online.
          
       2. Select Delegated permissions or Application permissions depending on the type you're adding.
       3. Search for a permission by its name. You need to add the following Office 365 Exchange Online permissions:
          • IMAP.AccessAsApp (application)
          • Mail.Send (delegated)
          • POP.AccessAsApp (application)
          • SMTP.SendAsApp (application)
            
            
            
       4. Select a permission, and then select Add permissions. Added Office 365 Exchange Online permissions look as follows:
          
       5. Some of the Office 365 Exchange Online permissions require administrator consent (their status will be Not granted for [your_organization] where [your_organization] is the name of your organization. To grant administrator consent, select the action Grant admin consent for [your_organization] action, and then select Yes on the confirmation message that appears.
          
12. Now you can return to the portal SMTP settings (described above) and set up SMTP authentication using the client ID, client secret, and tenant ID that you obtained in the Microsoft Azure portal. When configuring SMTP in the Xpand Portal backoffice:
    • In Media > Site settings SMTP settings: Choose OAuth 2.0 authentication
    • Network host: enter smtp-hve.office365.com (used for big volumes of data) or smtp-hve.office365.com 
    • Port: enter 465 (for SSL) or 587 (for STARTTLS, which is preferred for Microsoft Exchange)
    • Username: Enter the username of the Microsoft Entra ID account that will be used for sending emails.
    • Email: Enter the email of the Microsoft Entra ID account that will be used for sending emails.
    • Client ID: enter the client ID that was copied from the Application (Client) ID field in Azure Portal, on the app Overview page.
    • Client secret: enter the secret that was copied from the Value field in Azure Portal, on the Certificates & secrets page, on the Client secrets tab.
    • Token issue method: choose Authorization code (recommended) or Password
      • If you chose Authorization code the token issue method: In the Refresh token setting, select the Authorize action. Once you sign in, follow the instructions on screen and, if asked, grant permissions that the identity provider requests. As a result, the refresh token is issued by the identity provider and automatically filled in this setting. The password in this case is not used.
      • If you chose Password the token issue method: in the Password setting, enter the password from the Microsoft Entra ID account (the refresh token in this case is obtain automatically).
    • In Provider-specific settings:
      • Tenant ID: enter the tenant ID that was copied from the Directory (tenant) ID field in Azure Portal, on the app Overview page.
13. Fill in other SMTP settings as described above in this article, and save the changes.
14. In the backoffice, select Settings > More > Reload Application for changes in the SMTP settings to take effect.

After this, Microsoft Entra ID is fully configured as an SMTP provider and ready to send emails.

Configuring Google for SMTP

To configure Google for SMTP authentication:

1. Go to Google Cloud Platform and sign in with your Google account or create a new one.

   Note If you already have a registered app for your portal (which was created and configured, for example, for the SSO functionality), you don't need to create another app registration. In this case, skip the next step, and then expand the existing app configuration with additional setting that are required for SMTP authentication.

2. Create a project. If you already have a project 
   1. On the header, select the Select a project action.
   2. In the Select a project window that opens, select New project.
      
   3. In the New Project window, add the name of your app and select Create.
      
   4. On the OAuth Overview page, select Get started and fill in the required fields. 
      
      1. On the Branding page, enter the app name and user support email. This information is shown on the consent screen.
         
3. Select Create to finish the project creation.
   
4. On the OAuth Overview page, select Create OAuth client.
   

   Note If you already had an OAuth client configured for your portal, you can skip its creation and proceed to the step where you need to add a redirect URI for SMTP.

5. In the window that opens, on the navigation pane on the left, select OAuth consent screen.
6. In the Create OAuth client ID window, in the drop-down menu, select Web application.
   
7. In the Create OAuth client ID window that opens, enter the client name.
8. Under Authorised redirect URIs, select Add URI  and a URI for SMTP, and then select Create:
   
   https://[yourportaldomain]/security/Oauth/2.0/Oauth/HandleRedirectOAuth
   
   where [yourportaldomain] is the domain where your Xpand Portal solution is deployed.
   
   
   

   Note Google Cloud only allows redirect URIs with public top level domain (such as .com or .org). To be able to use Google as an SMTP provider, your portal domain must meet this requirement.

9. From the OAuth client created message that appears, copy the client ID from the Client ID field, and the client secret—from the Client secret field, as you will need them for further configuration of the SSO settings on Xpand Portal, and then select OK. If you used a project configured earlier, contact your administrator to get the client ID and client secret values.
   
10. Now you can return to the portal SMTP settings (described above) and set up SMTP authentication using the client ID and client secret that you obtained in the Google Cloud Platform. When configuring SMTP in the Xpand Portal backoffice:
    • In Media > Site settings SMTP settings: Choose OAuth 2.0 authentication
    • Network host: enter smtp.gmail.com 
    • Port: enter 465 (for SSL which is preferred for Google) or 587 (for STARTTLS)
    • Username: Enter the username of the Google account that will be used for sending emails.
    • Email: Enter the email of the Google account that will be used for sending emails.
    • Client ID: enter the client ID that was copied from the Client ID field in the Google Cloud Platform.
    • Client secret: enter the secret that was copied from the Client secret field in the Google Cloud Platform.
    • Token issue method: choose Authorization code (Google supports only this method)
    • In the Refresh token setting, select the Authorize action. Once you sign in (make sure you choose the correct Google account—the one that was used when configuring the Google identity provider), follow the instructions on screen and, if asked, grant permissions that the identity provider requests. As a result, the refresh token is issued by the identity provider and automatically filled in this setting.
11. Fill in other SMTP settings as described above in this article, and save the changes.
12. In the backoffice, select Settings > More > Reload Application for changes in the SMTP settings to take effect.

After this, Google is fully configured as an SMTP provider and ready to send emails using Google OAuth2 with XOAUTH2 authentication.