Setting Up Email Connections

As a system administrator, you set up the (secure) email connection for your system using SMTP as the email interface. Doing so allows your system to send emails when a Notification (CALL) object starts or when you use the SEND_MAIL script function. You can also use TLS to secure the SMTP connection and send secure emails via SMTPS. This functionality is available in the Automation Engine and certain Agents.

Important!

Using TLS to secure the SMTP connection requires a certificate. Make sure that it is available in the UC_TRUSTEDCERTS Storage object in Client 0, see UC_TRUSTEDCERTS Storage Object.
When you use the SMTP Parameters definition in the UC_CLIENT_SETTINGS also for the SEND_MAIL script function and the Notification (CALL) object, be aware that changing keys, for example, the SMTP_PROTOCOL, affects both, see SEND_MAIL and Notification (CALL).
Agents that support SMTP but not SMTPS ignore the keys that are relevant for TLS. If they are able to send emails, they do so using the PLAIN protocol, the definition of the SMTP_SERVER key and the default SMTP_PORT definition (25), which secures backward compatibility with Agents that do not support sending secure emails.

This page includes the following:

Overview

Establishing an email connection is the main requirement for the Automation Engine or an Agent to send emails - secure or not - to a user. You only need to configure the email connection for the Automation Engine as it automatically applies to all agents that support the sending of emails. The Administration perspective displays the value MAIL in the Services column of the Agents pane of all these agents.

Depending on the situation in which you send an email, the system either uses the Automation Engine or an agent. Make sure they can access the relevant directory if you attach files.

Important! Not all Agents support sending (secure) emails. Agents that support SMTP but not SMTPS ignore the keys that are relevant for TLS. If they are able to send emails, they do so using the PLAIN protocol, the definition of the SMTP_SERVER key and the default SMTP_PORT definition (25), which secures backward compatibility with Agents that do not support sending secure emails.

The table below shows which Agents support sending (secure) emails.

Agent	Send Email	Send Secure Email
BS2000	NO	NO
Database Agents	YES	YES
JMX	YES	YES
NSK	NO	NO
AS/400	NO	NO
PeopleSoft	YES	YES
Rapid Automation	YES	YES
SAP	YES	YES
UNIX: Linux x64 and PowerPC 64 LE	YES	YES
UNIX: Other	YES	NO
VMS	YES	NO
Windows	YES	YES
z/OS	NO	NO

Setting Up the (Secure) Email Connection

To set up the email connection - secured or not - you have to make sure that SMTP is configured to match your needs. The correct configuration depends on how do you want your system to send emails via the Notification (CALL) object or using the SEND_MAIL script function.

Setting Up SMTP for Notification (CALL) Objects

In this case, you can only configure one SMTP(S) server. The Automation Engine is used to send the emails.

Exception: If external job output files of jobs are attached, the email is sent through the agent on which the job has been executed. The notification aborts if the agent is not active, if the files cannot be found, or if the user does not have the required authorizations (the P - Open Report right for the JOBS and EXTREP authorization types). For more information, see Notification (CALL) and Notification Attributes.

To set up SMTP do the following:

Log into the relevant Client and open the UC_CLIENT_SETTINGS variable.
Open the UC_CLIENT_SETTINGS variable and define all relevant SMTP Parameters, see SMTP Parameters and UC_CLIENT_SETTINGS - Various Client Settings.

The SMTP_SERVER and SMTP_FROM_ADDR keys are always mandatory.

If you want to send secure emails, define the relevant protocol in the SMTP_PROTOCOL key. In this case, defining the SMTPS_CERT key is mandatory, too.

Important!

Make sure the relevant TLS certificate is available in the UC_TRUSTEDCERTS Storage object in Client 0, see UC_TRUSTEDCERTS Storage Object.
If you define the SMTP parameters in Client 0, that set up applies to all Clients in your system.

If sending the email fails, the Notification (CALL) object aborts and returns a corresponding message. Emails that have been sent successfully are logged in the reports of the Notification (CALL) object. For more information, see Notification (CALL).

Setting Up SMTP for the SEND_MAIL Script Function

In this case, emails are either sent through the Automation Engine or, if defined, an Agent. For more information ,see SEND_MAIL. This option also allows you to set up one or more than one SMTP(S) servers with different configurations.

If you decide to use only one SMTP(S) server, you can use the SMTP Parameters of the UC_CLIENT_SETTINGS variable.

If you want to use more than one SMTP(S) server with different configurations, you can use the UC_SMTP_MYSERVER variable, defining one variable for each server (for example, UC_SMTP_MYSERVER1, UC_SMTP_MYSERVER2), see UC_SMTP_MYSERVER - SMTP Variable. The variable supports the same SMTP parameters as the UC_CLIENT_SETTINGS. However, it overrides the UC_CLIENT_SETTINGS if it is called when using the SEND_MAIL script function. The server name you define for each variable must match the MYSERVER parameter used in the SEND_MAIL script function.

To set up either option, do the following:

Log into the relevant Client and, depending on the option that you want to implement, open either the UC_CLIENT_SETTINGS or the UC_SMTP_MYSERVER variable, see SMTP Parameters or UC_SMTP_MYSERVER - SMTP Variable, respectively.
Once you have the relevant variable open, define all relevant SMTP Parameters

The SMTP_SERVER and SMTP_FROM_ADDR keys are always mandatory.

If you want to send secure emails, define the relevant protocol in the SMTP_PROTOCOL key. In this case, defining the SMTPS_CERT key is mandatory, too.
Use a script with the SEND_MAIL script function to verify your settings.

Example:

The following example sends an email to exactly one user; the cc parameter is not used. If the result shown in the activation report is 0, the email was successfully sent.

:SET &OUT# = SEND_MAIL('test@maildomain.com',,'Test Email','This is a test email')

:PRINT &OUT#

Result shown in the activation report:

2023-08-17 15:01:38 - U00020408 0000000000000000
Ensure that the receiving email server processes the email properly and your email reaches the designated recipients.

SEND_MAIL does not output any information in the activation report. However, you can check the return code of this function and have a corresponding message printed. Also, script processing continues even if an error occurs but you can use the :ON_ERROR script function to define an appropriate reaction. For more information ,see :ON_ERROR.

Additionally, the SEND_MAIL_DEFAULT parameter of the UC_CLIENT_SETTINGS variable allows you to define a default Agent and Login object to be used when using the SEND_MAIL scripting function to send emails using an Agent. For more information, see SEND_MAIL_DEFAULT.