Email Settings
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.
Classic SMTP Profile Settings​
Below is a list of properties available on a classic SMTP server connection.
Main​
| Property Name | Property Description |
|---|---|
| Name | The name of the SMTP profile. |
| Description | A description of the SMTP profile. |
SMTP Server Settings​
| Property Name | Property Description |
|---|---|
| Hostname | Hostname of the SMTP server to send email through. |
| Port | Port SMTP service is running on. Default is 25. |
| Use SSL/TLS | Connect using dedicated SSL/TLS. Default is false. |
| Use STARTTLS | Enable 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. |
| Username | The username the Gateway will use when authenticating against the mailserver. This is only required if the SMTP server expects authentication. |
| Password | The password the Gateway will use when authenticating against the mailserver. This is only required if the SMTP server expects authentication. |
| Password | Retype password for verification. |
Advanced Properties​
| Property Name | Property Description |
|---|---|
| SMTP Timeout | Timeout (in milliseconds) to use when connecting to, reading from, and writing to the SMTP server. Default is 10,000. |
| Debug Mode Enabled | Enable 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​
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.
Main​
| Property Name | Property Description |
|---|---|
| Name | The name of the SMTP profile. |
| Description | A description of the SMTP profile. |
SMTP Server Settings​
| Property Name | Property Description |
|---|---|
| Hostname | Hostname of the SMTP server to send email through. |
| Port | Port SMTP service is running on. Default is 25. |
| Use SSL/TLS | Connect using dedicated SSL/TLS. Default is false. |
| Use STARTTLS | Enable 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​
| Property Name | Property Description |
|---|---|
| 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. |
| Interactive | If 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. |
| Scope | The OAuth 2.0 scope values representing the access token's set of permissions requested by the Gateway. |
Advanced​
| Property Name | Property Description |
|---|---|
| SMTP Timeout | Timeout (in milliseconds) to use when connecting to, reading from, and writing to the SMTP server. Default is 10,000. |
| Debug Mode Enabled | Enable email session debugging. Information is printed to standard output (wrapper.log). Default is false. |
| SSL/TLS Protocols | A comma separated list of protocols that will be allowed if connecting via SSL/TLS. Default is TLSv1.2. |
Advanced OAuth2 Settings​
| Property Name | Property Description |
|---|---|
| Access Token Timeout | Amount 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 Expiration | The 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 Expiration | The 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 Parameters | Add any additional parameters which should be encoded on the OAuth 2.0 authorization request (interactive only). |
| Additional Authorization Code Access Token Request Parameters | Add 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 Parameters | Add 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 Parameters | Add an additional parameters which should be encoded on the OAuth 2.0 access token request granted using a refresh token (interactive only). |
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.
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.
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.
Click on More, and then on manage token.
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.
Since we are using a Google Email Profile, we are redirected to a Google permission prompt. Click Allow to continue.
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.
Navigate to your OAuth2 Email Profile. Click on More, and then test.
This will bring you to a page where you can compose your test email.
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.
If the email sent successfully, you should receive a notification below the Send Test Email button.
