Email Messages

A Email Message notification type sends an email message via an SMTP server or Graph API server. This notification type is also used to send a notification as an SMS text message to a mobile phone. The GNS must be configured with authorization mode to indicate the type of server used, the server name, and authentication credentials.

SMTP Server

For notifications sent via SMTP, the GNS must be configured with the SMTP server information. Keywords in the configuration file specify the necessary SMTP parameters. The GNS Configuration Tester utility (GNSConfig.exe) is provided for setting up this section of the configuration file so that the username and password can be encrypted, and test messages can be sent and retrieved. See GNS Configuration Tester Utility for more information.

OAuth (Graph API) Server

For notifications sent via OAuth, the GNS must be configured with the Graph API server information. Keywords in the configuration file specify the necessary Graph API parameters. The GNS Configuration Tester utility (GNSConfig.exe) is provided for setting up this section of the configuration file so that the keywords can be encrypted, and test messages can be sent and retrieved. See GNS Configuration Tester Utility for more information.

Note: Text tokens can be used in this type of notification to specify a dynamic message using data from the data Point Service, the Current Value Service, or the Facility Service. See Using Tokens in Notifications for more information.

See Acknowledging Notifications for information about how to acknowledge a notification by a reply email.

GNS Configuration File Keywords — SMTP

The following keywords must be configured in the Gns.cfg to enable SMTP mail message notifications. See the SMTP Mail Keywords for more information.

Keyword

Description

SMTP_HOST

SMTP_HOST specifies the SMTP server host name or IP address.

SMTP_PORT

SMTP_PORT specifies the port number used by the SMTP server. Usually port 25.

SMTP_RECEIVE_TIMEOUT

SMTP_RECEIVE_TIMEOUT specifies the maximum amount of time (in seconds) the GNS will wait for a response from the SMTP server.

SMTP_TLS_METHOD

SMTP_TLS_METHOD specifies the encryption method used for outgoing SMTP server sending email notifications.

There are three options; specify one or select one from the drop-down menu, if using the GNS Configuration Tester:

Method	Description	Preferred Port
NONE	Clear text, no encryption.	110
SSL/TLS	The entire transaction is encrypted from beginning to end. This is the default option.	995
STARTTLS	The initial connection is not encrypted, but after connection the remainder of the transaction is encrypted.	110

The decision about which port to use and which encryption method to choose should be made by your network administrator.

SMTP_USERNAME

SMTP_USERNAME specifies the username for the SMTP server for sending outgoing email messages. See Email Credentials for Basic Authorization for information about how the basic authorization keywords are used.

This keyword is encrypted with the common encryption key file if ENCRYPTION_KEY_FILE is enabled.

SMTP_PASSWORD

SMTP_PASSWORD specifies the user password for the SMTP server for sending outgoing email messages. See Email Credentials for Basic Authorization for information about how the basic authorization keywords are used.

This keyword is encrypted with the common encryption key file if ENCRYPTION_KEY_FILE is enabled. Once encrypted, password keywords for the email server cannot be decrypted.

Shared Keywords

If authentication credentials are shared by SMTP and the POP servers, the following keywords must be configured. See Email Credentials for Basic Authorization for information about how the basic authorization keywords are used. See the Shared Mail Settings Keywords for more information.

Keyword	Description
EMAIL_ADDRESS	EMAIL_ADDRESS specifies the return (from) address for acknowledgment reply emails, such as name@company.com. This is the return address that will show on the outgoing email messages. If using OAuth 2.0 this must be a user on Office 365 with a Business Standard license.
EMAIL_USERNAME	EMAIL_USERNAME specifies the shared username for the SMTP and POP email servers. See Email Credentials for Basic Authorization for information about how the basic authorization keywords are used. This keyword is encrypted with the common encryption key file if ENCRYPTION_KEY_FILE is enabled.
EMAIL_PASSWORD	EMAIL_PASSWORD specifies the shared password for the SMTP and POP email servers. See Email Credentials for Basic Authorization for information about how the basic authorization keywords are used. This keyword is encrypted with the common encryption key file if ENCRYPTION_KEY_FILE is enabled. Once encrypted, password keywords for the email server cannot be decrypted.

Keyword

Description

EMAIL_ADDRESS

EMAIL_ADDRESS specifies the return (from) address for acknowledgment reply emails, such as name@company.com. This is the return address that will show on the outgoing email messages. If using OAuth 2.0 this must be a user on Office 365 with a Business Standard license.

EMAIL_USERNAME

EMAIL_USERNAME specifies the shared username for the SMTP and POP email servers. See Email Credentials for Basic Authorization for information about how the basic authorization keywords are used.

This keyword is encrypted with the common encryption key file if ENCRYPTION_KEY_FILE is enabled.

EMAIL_PASSWORD

EMAIL_PASSWORD specifies the shared password for the SMTP and POP email servers. See Email Credentials for Basic Authorization for information about how the basic authorization keywords are used.

This keyword is encrypted with the common encryption key file if ENCRYPTION_KEY_FILE is enabled. Once encrypted, password keywords for the email server cannot be decrypted.

GNS Configuration File Keywords — OAuth (Graph API)

The following keywords must be configured in the Gns.cfg to enable Graph API mail message notifications. See the Graph API Mail Keywords for more information.

Keyword	Description
EMAIL_OAUTH_TYPE	EMAIL_OAUTH_TYPE specifies the provider for the OAuth2 authorization mode. If you are using OAuth2 authentication, the only provider type is Microsoft. Microsoft uses the Graph API to enable authorization access to Microsoft Cloud service resources, including Microsoft 365 and Azure Active Directory.
EMAIL_OAUTH_AUTHORITY	EMAIL_OAUTH_AUTHORITY specifies the Authority URI for the OAuth2 authority. The authority URI is a URL that indicates a directory that the Microsoft Authentication Library (MSAL) can request tokens from.
EMAIL_OAUTH_TENANT	EMAIL_OAUTH_TENANT specifies the Authority tenant ID for the OAuth2 authority. The tenant ID is a globally unique identifier (GUID) associated with the Microsoft Azure Active Directory (Azure AD) instance for your organization.
EMAIL_OAUTH_CLIENT_ID	EMAIL_OAUTH_CLIENT_ID specifies the Client ID assigned by the OAuth2 authority to the GNS. The client ID is created when you register the GNS with the Microsoft Azure AD portal. This keyword is encrypted with the common encryption key file if ENCRYPTION_KEY_FILE is enabled.
EMAIL_OAUTH_CLIENT_SECRET	EMAIL_OAUTH_CLIENT_SECRET specifies the Client secret known only to the OAuth2 authority and the GNS. The client secret is created when you register the GNS with the Microsoft Azure AD portal. This keyword is encrypted with the common encryption key file if ENCRYPTION_KEY_FILE is enabled.
GRAPH_RESPONSE_TIMEOUT	GRAPH_RESPONSE_TIMEOUT specifies the maximum amount of time (in seconds) the GNS will wait for a response from the Graph endpoint (e.g. https://graph.microsoft.com). The default is 30 seconds.

See Configuring Microsoft 365 to work with Graph API for assistance on how to configure Azure Active Directory, Microsoft 365 server, and CygNet’s GnsConfig utility to work together to send and receive email messages using Graph API.

Resending Failed Email Notifications

The GNS Resend Queue will report a "Retrying On Fail" state when the GNS is planning on resending an email notification that has failed. The "Retrying On Fail" feature applies only to email notifications. Note that an older CygNet Explorer client may display a state of "Unknown" when the new state of "Retrying On Fail" occurs.

Two keywords to the Shared Mail Settings section of the Gns.cfg are available to configure the resending of email notifications that have failed to send for whatever reason.

Keyword	Description
EMAIL_SEND_FAIL_RETRY_MAX_ATTEMPTS	EMAIL_SEND_FAIL_RETRY_MAX_ATTEMPTS specifies the maximum number times the GNS will attempt to resend a failed notification email. Valid values are 0 to 999; default value is 0.
EMAIL_SEND_FAIL_RETRY_DELAY	EMAIL_SEND_FAIL_RETRY_DELAY specifies the delay in seconds between retries when resending a failed notification email. Valid values are 1 to 999; default value is 1.