Disclaimer

Your use of this download is governed by Stonebranch’s Terms of Use.

Version Information

Template Name	Extension Name	Version	Status
Email	ue-email	1.0.0	Fixes and new Features are introduced.

Refer to Changelog for version history information.

Overview

The Email Integration allows you to send emails through SMTP and Microsoft Graph API, offering configurable options for recipients, message content, and file attachments.

Key Features

Feature	Description
Send Email	Send emails via SMTP using an app password or through the Microsoft Graph API with app-only authentication, supporting multiple recipients, attachments, and both plain text and HTML formats for the message body.

Requirements

This integration requires a Universal Agent and a Python runtime to execute the Universal Task.

Area	Details
Python Version	Requires Python 3.11.
Universal Agent	Compatible with Universal Agent for Windows x64 and version >= 7.6.0.0 Compatible with Universal Agent for Linux and version >= 7.6.0.0.
Universal Controller	Universal Controller Version >= 7.6.0.0.
Network and Connectivity	Network connectivity towards SMTP server and Microsoft Graph API is required.
Microsoft Graph API	Microsoft Graph API version v1.0.

Supported Actions

Action: Send Email

Send emails using SMTP or Microsoft Graph API. Specify recipients (To, Cc, Bcc) directly in their respective fields or dynamically through UAC variables for To and Cc. The email body can be configured as plain text or HTML using the Body field or a UC Script. Attach files by providing full paths or wildcard patterns. Authentication options include app password for SMTP and app-only authentication for Microsoft Graph API.

Configuration examples

App Password Authentication


Send Simple Plain Text Email.	Send HTML Email with Variables, Body as Script and Attachments using Wildcards.

Microsoft App Only Authentication


Send a plaintext email using Microsoft App Only Authentication.	Send an HTML email using Microsoft App Only Authentication attaching specific files.

Action Output

Output Type

Description

Examples

EXTENSION

The extension output provides the following information:

”exit_code”, ”status_description”: General info regarding the task execution.
”invocation”.”fields”: The task configuration used for this task execution.
“result”.“errors“: List of errors that might have occurred during execution.

Successful scenario

{
	"exit_code": 0,
	"status_description": "Task executed successfully",
	"invocation": {
		"extension": "ue-email",
		"version": "1.0.0",
		"fields": {...}
	}
}

Failed execution scenario - App Password

{
	"exit_code": 1,
	"status_description": "Execution Failed: SMTP error occurred: (535, b'5.7.8 Username and Password not accepted. For more information, go to\n5.7.8 https://support.google.com/mail/?p=BadCredentials 5b1f17b1804b1-432dab80869sm158919065e9.22 - gsmtp')",
	"invocation": {
		"extension": "ue-email",
		"version": "1.0.0",
		"fields": {...}
	},
	"result": {
		"errors": [
			"Execution Failed: SMTP error occurred: (535, b'5.7.8 Username and Password not accepted. For more information, go to\n5.7.8 https://support.google.com/mail/?p=BadCredentials 5b1f17b1804b1-432dab80869sm158919065e9.22 - gsmtp')"
		]
	}
}

Failed execution scenario - Microsoft App unsafe-Only

{
	"exit_code": 1,
	"status_description": "Execution Failed: 400 Client Error: Bad Request for url: https://login.microsoftonline.com/3f4d7e2b-8a6c-45f9-b123-9876dcba5432/oauth2/v2.0/token",
	"invocation": {
		"extension": "ue-email",
		"version": "1.0.0",
		"fields": {...}
	},
	"result": {
		"errors": [
			"Execution Failed: 400 Client Error: Bad Request for url: https://login.microsoftonline.com/3f4d7e2b-8a6c-45f9-b123-9876dcba5432/oauth2/v2.0/token"
		]
	}
}

Input Fields

Name	Type	Description	Version Information
Action	Choice	The action performed upon the task execution. Send Email (default)	Introduced in 1.0.0
Authentication Method	Choice	The authentication method to be used for connecting to the email service. The following options are available. App Password Authentication (default) Microsoft App Only Authentication	Introduced in 1.0.0
App Password Credentials	Credential	App Password Credentials for App Password Authentication. The App Password Credentials definition should be as follows: Sender Email Address as "Runtime User". App Password as "Runtime Password". Required when Authentication Method is “App Password Authentication“.	Introduced in 1.0.0
Microsoft App Only Credentials	Credential	Microsoft App Only Credentials for Microsoft App Only Authentication. The Microsoft App Only Credentials definition should be as follows: Azure Client ID as "Runtime User". Azure Client Secret as "Runtime Password". Required when Authentication Method is “Microsoft App Only Authentication“.	Introduced in 1.0.0
Enable STARTTLS	Checkbox	Enables STARTTLS encryption method for email transmission. When disabled, alternative SSL/TLS encryption method will be enabled. Required when Authentication Method is “App Password Authentication“.	Introduced in 1.0.0
SMTP Server	Text	The SMTP server for email transmission. For example "smtp.gmail.com" Required when Authentication Method is “App Password Authentication“.	Introduced in 1.0.0
SMTP Port	Text	The port number for SMTP server connection. The default values are the following. 587 - STARTTLS (Enable STARTTLS checked) 465 - SSL/TLS (Enable STARTTLS unchecked) Required when Authentication Method is “App Password Authentication“.	Introduced in 1.0.0
Tenant ID	Text	The unique identifier of the Azure Active Directory (Azure AD) tenant associated with the Microsoft 365 account used for sending emails. Required when Authentication Method is “Microsoft App Only Authentication“.	Introduced in 1.0.0
From	Text	The email address of the sender. Required when Action is “Send Email“.	Introduced in 1.0.0
To	Text	The email address(es) of the recipient(s). At least one required when Action is “Send Email“. Multiple To recipients are separated with comma directly in the field or using a UAC Variable. Only the name of the variable is required in the text field.	Introduced in 1.0.0
To Variable	Checkbox	Enables configuring the To recipient(s) as a UAC Variable. Required when Action is “Send Email“.	Introduced in 1.0.0
Cc	Text	The email address(es) of the Cc recipient(s). Multiple Cc recipients are separated with comma directly in the field or using a UAC Variable. Only the name of the variable is required in the text field.	Introduced in 1.0.0
Cc Variable	Checkbox	Enables configuring the Cc recipient(s) as a UAC Variable. Required when Action is “Send Email“.	Introduced in 1.0.0
Bcc	Text	The email address(es) of the Bcc recipient(s). Multiple Bcc recipients are separated with comma directly in the field	Introduced in 1.0.0
Subject	Text	The subject of the email message.	Introduced in 1.0.0
Body Type	Choice	The format of the body content. The following options are available. Plain Text (default) HTML Content	Introduced in 1.0.0
Body as Script	Checkbox	Enables using a UC Script for generating the body content.	Introduced in 1.0.0
Body	Text	The body of the email message. Visible when Body as Script is unchecked.	Introduced in 1.0.0
Body Script	Script	UC Script for generating the body content. Visible when Body as Script is checked.	Introduced in 1.0.0
Attachment(s)	Text	The path of the attachment(s) to be sent with the email message. Multiple paths to the attachments are separated with comma. File paths can include specific filenames or wildcards (wildcards are supported for the filenames, not for directories)	Introduced in 1.0.0

Environment Variables

Variable: UE_HTTP_TIMEOUT

This environment variable defines the global timeout value for sending the email across all HTTP requests. It affects both connection and read timeouts, preventing requests from hanging.

Accepted values: Positive integer (in seconds).

If the environment variable is not set, the timeout will default to 60 seconds.

Exit Codes

Exit Code	Status	Status Description	Meaning
0	Success	”Task executed successfully.”	Successful Execution
1	Failure	“Execution Failed: <<Error Description>>”	Generic Error. Raised when not falling into the other Error Codes.

STDOUT and STDERR

STDOUT is empty and STDERR provides additional information to the user.

Backward compatibility is not guaranteed for the content of STDOUT/STDERR and can be changed in future versions without notice.

How To

Import Universal Template

To use the Universal Template, you first must perform the following steps.

This Universal Task requires the Resolvable Credentials feature. Check that the Resolvable Credentials Permitted system property has been set to true.
To import the Universal Template into your Controller, follow these instructions.
When the files have been imported successfully, refresh the Universal Templates list; the Universal Template will appear on the list.

Modifications of this integration, applied by users or customers, before or after import, might affect the supportability of this integration. For more information refer to Integration Modifications.

Integration Modifications

Modifications applied by users or customers, before or after import, might affect the supportability of this integration. The following modifications are discouraged to retain the support level as applied for this integration.

Python code modifications should not be done.
Template Modifications
- General Section
  - "Name", "Extension", "Variable Prefix", and "Icon" should not be changed.
- Universal Template Details Section
  - "Template Type", "Agent Type", "Send Extension Variables", and "Always Cancel on Force Finish" should not be changed.
- Result Processing Defaults Section
  - Success and Failure Exit codes should not be changed.
  - Success and Failure Output processing should not be changed.
- Fields Restriction Section
  The setup of the template does not impose any restrictions. However, concerning the "Exit Code Processing Fields" section.

i. Success/Failure exit codes need to be respected.

ii. In principle, as STDERR and STDOUT outputs can change in follow-up releases of this integration, they should not be considered as a reliable source for determining the success or failure of a task.

Users and customers are encouraged to report defects, or feature requests at Stonebranch Support Desk.

Document References

This document references the following documents:

Document Link	Description
Universal Templates	User documentation for creating, working with and understanding Universal Templates and Integrations.
Universal Tasks	User documentation for creating Universal Tasks in the Universal Controller user interface.

Changelog

ue-email-1.0.0 (2024-12-19)

Initial Version

UAC Utility: Email