Configure SMTP Gateway

An SMTP Gateway, also known as an SMTP relay, is a service or server that acts as an intermediary between email clients and email servers to facilitate the delivery of emails. When a user sends an email from their email client, the email is first sent to the SMTP Gateway. The SMTP Gateway then processes the email and forwards it to the recipient's email server. The recipient's email server then delivers the email to the recipient's inbox.

SMTP API Gateway is a service that provides an API interface to interact with SMTP Gateway functionality. It allows developers to integrate SMTP Gateway functionality into their applications to send Email.

User Persona: App Administrator

On configuring SMTP the App Administrator can test if it can successfully send mail. Let’s explore more on SMTP configuration and testing.

• Configure

• Edit

• Send Test Mail

• View Test History

Configure SMTP Gateway

The SMTP Gateways configured within the application are Primary and Secondary. The Types of SMTP used to send email are Relay and API.

To configure SMTP Gateway, perform the following steps:

1. Log in as an App Administrator.

   

   Figure: App Portal

   
   

2. Click the Application Group tab and select an Application.

   Example: Application Groups will be configured as IT, HR, Finance, etc, and Applications are Asset Management, Service Management, etc.

   

   Figure: Applications
   
   

3. Click the settings gear icon on the top panel, navigate to Design Studio > Applications > Notification Type > SMTP, and click Add SMTP Gateway.

   

   Figure: SMTP Gateway

   
   

4. Select and Enter the appropriate details in the required fields. Refer to the following sections about the configuration details.

   • General

   • Primary and Secondary Gateways

     Gateways and its Dependency on the Platform Components

     The system provides two types of SMTP gateways namely:

     Relay

     API

     Multiple Primary and Secondary gateways can be configured for different Domains, OUs & Tenants, and also for the Global level. However, the following rules apply:

     • A Global level has only one Primary & Secondary gateway.
       

     • Each Tenant can have only one Primary and Secondary gateway.
       

     • Each Sub Domain can have one or more Primary and Secondary gateways.

       Example: Sub Domain with a combination of the following Tenants can have multiple primary and secondary gateways.

       HR and IT can have a Primary and Secondary gateway.

       IT and Finance can have a Primary & Secondary gateway.
       

     • Each Domain can have one or more Primary & Secondary gateways based on different combinations.
       

     • If any two combinations are similar, then the second similar combination becomes invalid.

   

   Figure: Add SMTP Gateway Configuration

General

This section allows to configuration of SMTP at the platform levels such as Global, Domain, Sub Domain, and Tenant.

Primary and Secondary Gateways

The SMTP Type field will be shown in both Primary and Secondary gateways.

Figure: SMTP Types on Primary and Secondary Gateways

Note

The primary gateway is a mandatory configuration for any level of gateway settings. Based on the selected SMTP type the configuration screen is displayed.

The following SMTP types are available in the dropdown list.

• Relay

• API

The maximum number of SMTP scenarios are as follows:

Relay

SMTP Relay is a process of sending emails through a SMTP server. SMTP servers are often used as relays because they can handle large volumes of emails, and ensure that emails are delivered to their intended recipients.

To configure Relay Type, perform the following steps:

1. Select Relay as SMTP Type to send email through the SMTP Server.

   

   Figure: Relay SMTP
   

2. Enter appropriate details in the required fields.
   
   The following table provides details regarding Field Description.

   Field	Description
   SMTP Type	Specify the Type of SMTP, as Relay is selected from the previous action, all the Relay configuration fields are displayed.
   From Name	Enter From Name, this is the name recipients will see as part of the From or Sender value when they receive the message.
   From Email ID	Enter From Email ID, this is the Email Address that will be used to send emails to the recipients.
   Host	Enter SMTP Host, this is your outgoing mail server (example: smtp.office365.com)
   Port	Enter the Port number, this is the Port that will be used to relay outbound mail to your mail server. Example: 587
   Encryption	Select any one Encryption type, from the following options: None SSL TLS
   Authentication	Select Authentication. Yes: Email through the SMTP Relay server will have an authentication. Selecting Yes will enable Username and Password fields. By default, this is always selected for Relay emails. No: Email through the SMTP Relay server will not have an authentication and Username and Password fields will not be displayed.
   Username	Enter the Username, the Username created here will be used to login to the SMTP mail server.
   Password	Enter Password, a password for the mail server is set here. This password will be used to login to the SMTP mail server.
   Active	Enable Active control to configure SMTP Type as Active and disable to configure SMTP Type as Inactive. If enabled, SMTP Type for Primary or Secondary configuration will be triggered. If disabled, SMTP Type for Primary or Secondary configuration will not be triggered.
   Submit	Click Submit, to save the SMTP configuration and view it on the List page.
   Cancel	Click Cancel, to exit from the configuration.

API

API (Application Programming Interface) is a set of protocols, tools, and standards for building software applications. An API allows different software applications to communicate with each other. When the SMTP Type selected is API, then the configuration fields related to the API type are displayed.

To configure API Type, perform the following steps:

1. Select API as SMTP Type, to send email through the application interface.

   

   Figure: API SMTP Gateway
   

2. Enter appropriate details in the required fields.
   
   The following table provides details regarding Field Description.

   Field	Description
   SMTP Type	Specify the Type of SMTP, as API is selected from the previous action, all the API configuration fields are displayed.
   From Name	Enter From Name, this is the name recipients will see as part of the From or Sender value when they receive the message.
   From Email ID	Enter From Email ID, this is the Email Address that is used to send emails to the recipients.
   API	Select API, the dropdown will display all the configured APIs. To configure a new API, refer to API Configuration.
   Submit	Click Submit, to save the SMTP configuration and view it on the List page.
   Cancel	Click Cancel, to exit from the configuration.

Edit SMTP Gateway

To Edit an SMTP Gateway, perform the following steps:

1. Select the required ID on the SMTP list page.

   

   Figure: SMTP Gateway
   

2. Make the required changes and click Update.

   Upon updating, you will be navigated to the List page.

   

   Figure: Update SMTP

Send Test Mail

The SMTP Gateway configuration page will have the option to test the configured SMTP gateways by sending a test email. Once all the configurations are completed, go back to the configured SMTP from the List page, on the configuration screen just below the Primary and Secondary gateways there will be an option available to send Test Mail.

To send a test mail, perform the following:

1. Click SMTP  ID on the SMPT list page.

   

   Figure: SMTP List
   

2. SMTP configuration screen is displayed, click Send Test Mail to check the SMTP configuration.

   

   Figure: SMTP Send Test Mail
   

3. The Test Mail screen is displayed.

   

   Figure: Test Mail
   

4. Select and enter appropriate details in the Test Mail configuration. Click Send to test SMTP or click Cancel to exit from the configuration screen.

   
   The following table provides details about the Field Description.

   Field	Description
   Test For	For the configured Global/Domain/Sub Domain/Tenant level there is an option to test the gateway configuration to see if it's working as expected. This Test For dropdown provides two options as follows: Primary Gateway: When Primary is selected, the system sends the test mail from Primary Gateway. Secondary Gateway: When Secondary is selected, the system sends the test mail from the Secondary Gateway. Either Primary or Secondary can be selected at a time. Figure: Test For
   To	By default, the login person’s Email ID will be auto-captured in the To field. However, the login person cannot edit the field to change the email id. Note Sending Emails from here is only for testing purposes and no official communication is to be done from here.
   Subject	To avoid any misuse of this function the system will pre-populate a message in the Subject textbox with a message as Test Email.
   Body	To avoid any misuse of this function the system will pre-populate a message in the Subject textbox with a message This is an email for testing the SMTP Gateway. Please ignore. Note The name and email ID of the sender will be captured in the message.
   Response
   Status	Click Send to check the configuration. Response Description Success If the selected Gateway is configured as expected, then a Success message is displayed as Test Mail sent Successfully. Figure: Success Response Failed If the selected Gateway is configured incorrectly, then a Failed message is displayed as Test mail failed! Figure: Failed Response
   Display Type	Select Display Type from the dropdown, following options are displayed: Text: Selecting Text will display content in the Description field in Text format. JSON: Selecting JSON will display content in the Description field in JSON format.
   Description	The description contains the details that are configured in the selected API configuration, for more information, refer API Body.

View Test History

Upon testing SMTP, the Success or Failed responses are saved under Test History on the List page of SMTP Configuration. The History details are captured and presented in a list format where simple filters can be applied to view the required results.

To view the Test History, perform the following steps:

1. Navigate to the List page and select the configured SMTP ID.

   

   Figure: SMTP List
   

2. Click the Test History icon on the Top Panel.

   

   Figure: SMTP Gateway Details
   

3. Test Mail History details are displayed.

   

   Figure: Test Mail History