UC_SMTP_MYSERVER - SMTP Variable

This static variable allows you to configure more than one SMTP(S) server to establish the connection required to send emails via the Automation Engine or an Agent when using the SEND_MAIL script function. It is supplied with Client 0 and can be copied to other clients and customized as needed.

To do so, you define one UC_SMTP_MYSERVER variable for each server (UC_SMTP_MYSERVER1, UC_SMTP_MYSERVER2), making sure that you replace MYSERVER with the relevant server name (for example, UC_SMTP_LOCALHOST). The server name you define for each variable must match the MYSERVER parameter used in the SEND_MAIL script function. For more information ,see SEND_MAIL and Setting Up Email Connections.

Important!

  • The SMTP_SERVER and SMTP_FROM_ADDR keys are always mandatory.

  • When you select the STARTTLS or TLS protocols, defining the SMTPS_CERT key is mandatory, too. Make sure that the relevant certificate is available in the UC_TRUSTEDCERTS Storage object in Client 0, see UC_TRUSTEDCERTS Storage Object.

  • Not all Agents support sending (secure) emails, see Setting Up Email Connections.

  • 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 variable covers the following SMTP(S) parameters:

SMTP_FROM_ADDR

  • Description: (Mandatory) Email address of the sender.

  • Restart required: No

SMTP_LOGIN

  • Description: (Optional) Name of the Login object used to log on to the SMTP server. This Login object also allows you to store the credentials required for XOAuth2 authentication. For more information, see Login (LOGIN).

  • Restart required: No

SMTP_AUTH_METHOD

  • Description: (Optional) Specifies the SMTP authentication method.

  • Supported values: PLAIN, LOGIN, XOAUTH2

    If this parameter is not defined, the system attempts to authenticate using the PLAIN method first and the LOGIN method second, depending on server support. Both PLAIN and LOGIN authentication methods use a user name and password, as defined using the type MAIL in the Login object referenced in SMTP_LOGIN. For more information, see Login (LOGIN).

    When you select the XOAUTH2 authentication method, you must define the following keys either in the Login object referenced by SMTP_LOGIN or in the UC_SMTP_* variable:

    • SMTP_XOAUTH2_CLIENT_ID: Public identifier for the application requesting an access token.

    • SMTP_XOAUTH2_CLIENT_SECRET: (Optional) Confidential credential paired with the CLIENT_ID used by the application to authenticate to the authorization server.

    • SMTP_XOAUTH2_SCOPE: String defining the permissions or resources granted by the access token; in this case, allowing the application to send email on behalf of the user. For example,

      https://outlook.office.com/SMTP.Send

    • SMTP_XOAUTH2_URL: OAuth 2.0 endpoint where the client requests or exchanges tokens for authentication. For example,

      https://login.microsoftonline.com/<tenantId>/oauth2/v2.0/token

    Unlike PLAIN and LOGIN, XOAUTH2 requires additional parameters such as SMTP_XOAUTH2_CLIENT_ID, SMTP_XOAUTH2_SCOPE, and SMTP_XOAUTH2_URL. The SMTP_XOAUTH2_CLIENT_SECRET is optional and only required if no user name and password are defined in the associated Login object.

    Important! Define the XOAUTH2 parameters either in the Login object or in the UC_SMTP_* variable. Because SMTP_XOAUTH2_CLIENT_ID and especially SMTP_XOAUTH2_CLIENT_SECRET are sensitive values, consider storing them securely as SECRET entries in the Login object referenced by SMTP_LOGIN. Non-sensitive parameters such as SMTP_XOAUTH2_URL can be stored in the UC_SMTP_* variable, if you prefer.

  • Restart required: No

SMTP_MAX_ATTACHMENT_SIZE

  • Description: (Optional) Maximum size in bytes of the report file that is sent by email. This applies only to reports that are sent by email, but not to other types of attachments.

    In the Notification page of a Notification object, specify the RunID of the relevant task so that the corresponding reports can be attached to the message. For more information, see Notification (CALL).

  • Allowed values: 400 - 50000

    When the report file exceeds the maximum value, only the allowed size is read and sent. The file end includes the following note: Truncated through SMTP_MAX_ATTACHMENT_SIZE limit.

  • Default value: 8000

  • Restart required: No

SMTP_PORT

  • Description: (Optional) Port of the SMTP(S) server used to connect to the mail server.

    A port that supports TLS might be required when STARTTLS or TLS are set as the SMTP_PROTOCOL.

  • Default value: 25

  • Restart required: No

SMTP_PROTOCOL

  • Description: (Optional) The protocol that you want to use to establish the communication.

  • Allowed values: upper case, lower case, and mixed case letters

    • PLAIN (default)

      Sends emails through an unencrypted connection.

    • STARTTLS

      Sends emails through an opportunistic TLS connection. Depending on how your SMTP server is configured, you might also need to change SMTP_PORT to change its default behavior.

    • TLS

      Sends emails through a forced TLS connection. In this case, you require a port that supports TLS.

    When you select STARTTLS or TLS, it is mandatory to define the SMTPS_CERT parameter and point to the certificate that you want to use. Make sure that the relevant certificate has been uploaded to the UC_TRUSTEDCERTS Storage object in Client 0, see UC_TRUSTEDCERTS Storage Object.

  • Restart required: No

SMTP_REPLY_TO

  • Description: (Optional) Email address for the response.

  • Restart required: No

SMTP_SERVER

  • Description: (Mandatory) Host name of the SMTP server.

  • Restart required: No

SMTP_TIMEOUT

  • Description: (Optional) Maximum time in seconds that the system waits for an SMTP Server to respond.

  • Allowed values: 0 - 999

  • Default value: 20

  • Restart required: No

SMTPS_CERT

  • Description: (Mandatory, when STARTTLS or TLS are set as the SMTP_PROTOCOL)

    Name of the certificate stored in the UC_TRUSTEDCERTS Storage object in Client 0, see UC_TRUSTEDCERTS Storage Object.

    When you use an Agent to send secure emails, the system searches in the UC_TRUSTEDCERTS Storage object for the certificate that has been defined in the SMTPS_CERT key. The AE sends that file to the Agent, which uses it to send an email to the SMTP server. However, the Agent caches the certificate and only gets a new one if changes are made in the UC_TRUSTEDCERTS Storage object (changes trigger cache clearing).

  • Restart required: No

See also: