Email Profiles

In Ignition, there are several places that you might want to send an email from. Instead of setting up a new email server connection at each one, you can add Email Profiles in the Gateway Config section and reference them in other places. For example, you can use a pre-configured connection in any of these places:

  • Alarm Notification - While the alarm notification system allows you to set up an Email Notification Profile that is separate from the Email Profile, you can instead choose to use the settings configured in the Email Profile.
  • Report Schedules - When Scheduling an Email Action in a report, the Action requires a configured Email Profile before the report can be emailed out.
  • system.net.sendEmail() - Instead of manually entering in values for the Email Profile inside each of your scripts, this function can instead use the settings from an existing Email Profile.

Once your Email Profile is set up, you only need to reference the name of the connection and Ignition will take care of the rest.

Setting Up an Email Profile

The Email Settings page allows you to select either basic authentication or OAuth 2.0 and configure an Email Profile from there. These Email Profiles can be used by several different resources in the Gateway. This means that instead of setting up an Email Profile within each resource (i.e., Alarm Notification Profile, Reports, etc.), you can configure them once here, and have those resources all use the same SMTP server. You can find the Email Settings in the Config section of the Gateway under the Networking heading. Here, you can create a new Email Profile, or manage your existing profiles.

On this page ...

Classic SMTP Profile Settings

Below is a list of properties available on a classic SMTP server connection. 

Property NameProperty Description
Main
NameThe name of the SMTP profile.
DescriptionA description of the SMTP profile.
SMTP Server Settings
HostnameHostname of the SMTP server to send email through.
PortPort SMTP service is running on. Default is 25.
Use SSL/TLSConnect using dedicated SSL/TLS. Default is false.
Use STARTTLSEnable use of the STARTTLS command, allowing the connection to be upgraded to an SSL or TLS connection if supported by the server. This is not necessary for connections that are already SSL/TLS. Default is false.
UsernameThe username the Gateway will use when authenticating against the mailserver. This is only required if the SMTP server expects authentication.
PasswordThe password the Gateway will use when authenticating against the mailserver. This is only required if the SMTP server expects authentication.
PasswordRetype password for verification.
Advanced Properties
SMTP TimeoutTimeout (in milliseconds) to use when connecting to, reading from, and writing to the SMTP server. Default is 10,000.
Debug Mode EnabledEnable email session debugging. Information is printed to standard output (wrapper.log). Default is false.

SSL Protocols

A comma separated list of protocols that will be allowed if connecting via SSL/TLS. Default is TLSv1.2.


OAuth2 SMTP

The following feature is new in Ignition version 8.1.24
Click here to check out the other new features
Besides setting up classic SMTP Email Profiles, you can also set up OAuth2 SMTP Profiles. To set up an OAuth2 SMTP Profile, go to the Email Settings properties of the Gateway's Config section.

OAuth2 SMTP Profile Settings

Below is a list of properties available on an OAuth2 SMTP server connection.

Property NameProperty Description
Main
NameThe name of the SMTP profile.
DescriptionA description of the SMTP profile.
SMTP Server Settings
HostnameHostname of the SMTP server to send email through.
PortPort SMTP service is running on. Default is 25.
Use SSL/TLSConnect using dedicated SSL/TLS. Default is false.
Use STARTTLSEnable use of the STARTTLS command, allowing the connection to be upgraded to an SSL or TLS connection if supported by the server. This is not necessary for connections that are already SSL/TLS. Default is false.
OAuth2 Settings
Username

The username that the Gateway will use along with the access token which together make up the credential in the SMTP protocol's XOAUTH2 SASL authentication mechanism.

OAuth2 Client

The name of the OAuth2 Client which will be used by this Email Profile to obtain access tokens.

InteractiveIf enabled, user interaction is required to obtain access and refresh tokens (3-legged OAuth 2.0 flow). If disabled, user interaction is not required to obtain access tokens - the Gateway will obtain access tokens using its own client credentials (2-legged OAuth 2.0 flow). Default is false.
ScopeThe OAuth 2.0 scope values representing the access token's set of permissions requested by the Gateway.
Advanced
SMTP TimeoutTimeout (in milliseconds) to use when connecting to, reading from, and writing to the SMTP server. Default is 10,000.
Debug Mode EnabledEnable email session debugging. Information is printed to standard output (wrapper.log). Default is false.
SSL/TLS ProtocolsA comma separated list of protocols that will be allowed if connecting via SSL/TLS. Default is TLSv1.2.
Advanced OAuth2 Settings
Access Token TimeoutAmount of time in seconds to wait for a valid access token before giving up on sending an email. Values less than or equal to zero will cause the profile to expect a valid access token to be available immediately and will fail fast if one is not available at the time an email needs to be sent. Default is 120.
Default Access Token ExpirationThe amount of time in seconds before an access token expires by default. This value only applies for access tokens which do not have an explicit expiration from the authorization server. Values less than or equal to zero means access tokens do not expire by default. Default is 0.
Refresh Before ExpirationThe amount of time in seconds before an access token expires when a new token should be requested. Values less than or equal to zero results in new access token requests exactly when the last access token expires. Default is 300.
Additional Authorization Request ParametersAdd any additional parameters which should be encoded on the OAuth 2.0 authorization request (interactive only).
Additional Authorization Code Access Token Request ParametersAdd any additional parameters which should be encoded on the OAuth 2.0 access token request granted using an authorization code (interactive only).
Additional Client Credentials Access Token Request ParametersAdd any additional parameters which should be encoded on the OAuth 2.0 access token request granted using client credentials (non-interactive only).
Additional Refresh Token Access Token Request ParametersAdd an additional parameters which should be encoded on the OAuth 2.0 access token request granted using a refresh token (interactive only).

Note: When using OAuth2 Email Profiles, you must set up predefined OAuth2 Clients for authorization. An OAuth2 Client may be used for multiple OAuth2 Email Profiles. See the OAuth 2.0 Client page for more information.
Once you set up OAuth2 SMTP Email Profile, you will have options to manage your token, delete the SMTP Profile, or test it by composing and sending a test email.


Manage Token Example

This page will allow you to view the current state of the access token managed by the OAuth2 SMTP Email Profile. If the Email Profile has any issues obtaining or refreshing tokens, details about the issue(s) will be shown here. There will be actions you may take to correct the issue(s), such as granting a new access token, or manually refreshing an access token. In some cases, you may need to adjust your Email Profile configuration settings to fix a problem, depending on the error shown.

Note: The "Refresh Token" button will only be available if the OAuth2 SMTP Email Profile is not interactive OR if it is interactive and a refresh token is available. Additionally, the "Grant New Token" option will only be available when the Email Profile is interactive.

This option will allow you to grant the Client a new access token, or refresh the current token and it's expiration time.

  1. Set up your OAuth2 SMTP Email Profile if you haven't already. In this example, we will be using the OAuth2 Email Profile in the screenshot above.

  2. Click on "More", and then on "manage token".


  3. If you are using an interactive-based token, your access token will show as invalid the first time you click on "manage token". To fix this, click on "Grant New Token".



  4. Since we are using a Google Email Profile, we are redirected to a Google permission prompt. Click "Allow" to continue.



  5. After the authorization server grants the initial access token, you will be redirected back to the Gateway, After a few seconds, the Gateway will refresh, showing a valid access token.


Test OAuth2 Email Profile Example

This option will allow you to send a test email using the OAuth2 Email Profile and OAuth2 Client you set up.

  1. Navigate to your OAuth2 Email Profile. Click on "More", and then "test".



  2. This will bring you to a page where you can compose your test email.



  3. Fill out the form. The "From" field should be populated with the email address that will be sending the email, and the "To" field should be the test email's recipient. Click on "Send Test Email" when you are done.



  4. If the email sent successfully, you should receive a notification below the "Send Test Email" button.



  • No labels