Email from STEP

Multiple STEP components support using email to deliver data, error reports, workflow notifications, and messages via configuration of a mail server.

As defined below, a one-time STEP configuration of the connection to this mail server over SMTP (Simple Mail Transfer Protocol) is required.

Important: For Stibo Systems SaaS environments, a mail server is included and configured by default. To configure a different mail relay server, submit a Stibo Systems Service Portal ticket to request configuration, providing expected values for properties and jks file, if relevant.

Once configured, email can be generated from STEP in the following areas:

Asset Push - as defined in the Monitoring Asset Push topic and the Creating and Maintaining Asset Push Configurations topic
Bulk Updates using a business action - as defined in the Scheduling a Task Notification Email topic
Event Processors - as defined in the EP - Error Handling and Reporting topic
Export Manager - as defined in the Email Delivery Method topic
IIEPs - as defined in the IIEP - Error Handling & Reporting topic
OIEPs - as defined in the OIEP - Configuration Section topic
Workflows - as defined in the Send Email from a Workflow topic

Mail Server with TLS and OAuth On-Prem Configuration

When using OAuth 2.0 to send an email from STEP, first an access token is requested from an authorization service using a client id and a password a certificate. Once the authorization service accepts the request, it provides an access token with a limited lifetime to STEP, and during that lifetime, STEP uses that token to authenticate when sending email.

Using a mail server with TLS and OAuth 2.0 instead of Basic authentication, for example smtp.office365.com, requires the following setup:

For on-premises systems, as an admin user, log in to the STEP application server and edit the sharedconfig.properties file.
Add the case-sensitive Mail.UseTLS property, including 'true' as the value. For example,
```
Mail.UseTLS=true
```
Important: This property and value are required to activate the additional properties below.
Add the case-sensitive Mail.MailServerPort property, including the mail server port as the value. For example,
```
Mail.MailServerPort=587
```
Add the case-sensitive Mail.MailServerURL property, including the mail server URL as the value. For example,
```
Mail.MailServerURL=smtp.office365.com
```
Add the case-sensitive Mail.MailAuthenticationUser.Name property, including the authorized user name as the value. For example,
```
Mail.MailAuthenticationUser.Name=AuthUser
```
Add the case-sensitive Mail.OAuth.Scope property, including the mail server port as the value. For example,
```
Mail.OAuth.Scope=https://outlook.office365.com/.default
```

Add the case-sensitive Mail.OAuth.TokenService.URL property, including the appropriate URL. For example,

Mail.OAuth.TokenService.URL=https://login.microsoftonline.com/f3b75255-4214-4a54-b552-56ac6906ae88/oauth2/v2.0/token

Choose the appropriate authentication option:
- To use a Client ID / Client Secret, configure the following properties:
  - Add the case-sensitive Mail.OAuth.ClientID property, including the Client ID as the value. For example,
```
Mail.OAuth.ClientID=b3118bec-cc88-4c90-b202-5aa3f67f6ff8
```
  - Add the case-sensitive Mail.OAuth.ClientSecret property, including the secret. For example,
```
Mail.OAuth.ClientSecret=HST8Q~egaNMbB_CeZg8S8G5RhgeF1bMYwSSpUb8z
```
- To use a Certificate, configure the following properties:
  - Add the case-sensitive Mail.OAuth.ClientKeyStore property, including the secret. For example,
```
Mail.OAuth.ClientKeyStore=/home/mailserverconfig/keystore.jks
```
  - Add the case-sensitive Mail.OAuth.ClientKeyStore.Password property, including the secret. For example,
```
Mail.OAuth.ClientKeyStore.Password=Pa55worD
```
For on-premises systems, restart the STEP application server to apply the changes to the properties file.

Mail Server with TLS and Basic Authentication On-Prem Configuration

When using basic authentication, every time a user or functional area within STEP sends an email, a username and password is exchanged with the configured mail relay service. Basic authentication is increasingly considered outdated and vulnerable, and many widely used email services, such as Office 365, plan to discontinue support.

Using a mail server with TLS and basic authentication, for example smtp.office365.com, requires the following setup:

Note: Microsoft has announced that Basic authentication will be deprecated for client submissions within their Exchange Online / Office 365 mail service in September 2025. Search the web for details.

For on-premises systems, as an admin user, log in to the STEP application server and edit the sharedconfig.properties file.
Add the case-sensitive Mail.UseTLS property, including 'true' as the value. For example,
```
Mail.UseTLS=true
```
Important: This property and value are required to activate the additional properties below.
Add the case-sensitive Mail.MailServerPort property, including the mail server port as the value. For example,
```
Mail.MailServerPort=587
```
Add the case-sensitive Mail.MailServerURL property, including the mail server URL as the value. For example,
```
Mail.MailServerURL=smtp.office365.com
```
Add the case-sensitive Mail.DefaultFromMailAddress property, including the default mail address displayed in the 'From' field as the value. For example,
```
Mail.DefaultFromMailAddress=noreply@mailserver.com
```
If no default mail address is provided, STEP sets the default 'From' email address as 'noreply@step-system.invalid'.
Add the case-sensitive Mail.MailAuthenticationUser.Name property, including the authorized user name as the value. For example,
```
Mail.MailAuthenticationUser.Name=AuthUser
```
Add the case-sensitive Mail.MailAuthenticationUser.Password property, including the authorized user password as the value. For example,

Note: This property holds the password of the authorized user. When that password changes, the value on this property must also be updated.

If no default mail address is provided, STEP sets the default 'From' email address as 'noreply@step-system.invalid'.
```
Mail.MailAuthenticationUser.Password=AuthPassword
```
Restart the STEP application server to apply the changes to the properties file.

Standard Mail Server On-Prem Configuration

Using the standard mail server functionality requires the following setup:

For on-premises systems, as an admin user, log in to the STEP application server and edit the sharedconfig.properties file.
Add the case-sensitive Mail.MailServerURL property, including the mail server URL as the value. For example,
```
Mail.MailServerURL=my.mailserver.com
```
Add the case-sensitive Mail.DefaultFromMailAddress property, including the default mail address displayed in the 'From' field as the value. For example,
```
Mail.DefaultFromMailAddress=noreply@mailserver.com
```
If no default mail address is provided, STEP sets the default 'From' email address as 'noreply@step-system.invalid'.
Restart the STEP application server to apply the changes to the properties file.