Disclaimer

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

Version Information

Refer to Changelog for version history information.

Overview

The Email Monitor integration provides robust email monitoring using IMAP and Microsoft Graph.

Put briefly, this integration allows you to monitor a mailbox for e-mails through filtering, do certain post-actions, and trigger Universal Events to trigger follow-up workflows or tasks.  

Key Features

Requirements

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

Supported Actions

There are two Top-Level actions controlled by the Action Field:

• Retrieve emails using IMAP with App Password Authentication
• Retrieve emails using Microsoft Graph with App Only Authentication

Both actions share the same capabilities related to email processing and post actions. 

Action Output

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

{
	"exit_code": 1,
	"status_description": "Execution Failed: The email file name format must contain at least one supported placeholder: {{ email.from_address }}, {{ email.date }}, {{ email.subject }}, or {{ nanoid() }}.",
	"invocation": {
		"extension": "ue-email-monitor",
		"version": "1.0.0",
		"fields": {...}
	},
	"result": {
		"errors": [
		"Execution Failed: The email file name format must contain at least one supported placeholder: {{ email.from_address }}, {{ email.date }}, {{ email.subject }}, or {{ nanoid() }}."
		]
	}
}

Configuration examples

Example: Simple task configuration for IMAP

The IMAP task uses App Password Authentication and SSL/TLS encryption on port 993 to securely check for new unread emails every 300 seconds since the application started. 

Example: GRAPH Example with post action and filters.

The MS Graph task uses App Only Authentication to connect, monitoring all existing and incoming emails (read and unread) from an Inbox, sent to specific multiple To recipients with specific Subject text, downloading emails using the default file name format and all attachments in the matching emails using custom file name format. The emails are monitored every 10 seconds. After processing, the emails are deleted.

Example: IMAP Example with post action and filters.

The IMAP task uses App Password Authentication with SSL/TLS encryption on port 993 to securely connect to the Gmail server. The task monitors for new emails from a specific sender and with a specific substring of the body message. Only the attachments matching the patterns in the Attachments field are downloaded, using the default file name format. The emails are monitored every 10 seconds, and the events are published with a specific tag. After processing, the emails are moved to a folder.

Importable Configuration Examples

This integration provides importable configuration examples along with their dependencies, grouped as Use Cases to better describe end to end capabilities. 

Initial Preparation Steps

• STEP 1: Go to Stonebranch Integration Hub and download  "UAC Utility: Email" and "UAC Utility: Email Monitor" integrations. Extract the downloaded archives on separate directories in a local drive.
• STEP 2: Locate and import the above integrations to the target Universal Controller. For more information refer to the How To section in this document.
• STEP 3: For "UAC Utility: Email Monitor", inside the directory named "configuration_examples" you will find a list of definition zip files. Upload them one by one respecting the order presented below, by using the "Upload" functionality of Universal Controller: 
  • variables.zip
  • credentials.zip
  • scripts.zip
  • tasks.zip
  • monitors.zip
  • workflows.zip
  • triggers.zip
• STEP 4: Update the uploaded UAC Credential entities introduced with proper Client ID / Client Secret
• STEP 5: Update the UAC global variables introduced with variables.zip file. Their name is prefixed with "ue_email_monitor". Review the descriptions of the variables as they include information on how should be populated.

Login to Universal Controller and:

• STEP 1: Click on "Tasks" → "All Tasks"
• STEP 2: Right click on the top of the column named "Name"
• STEP 3: Click "Upload..."

In the pop-up "Upload..." dialogue:

• STEP 1: Click "Choose File".
• STEP 2: Select the appropriate zip definition file and click "Upload".
• STEP 3: Observe the Console for possible errors.

Use Case 1: For each monitored email, trigger a Workflow

Description

In this Use Case, emails are the triggering point for executing a workflow. Emails can be filtered based on their content and attributes. Workflows are executed and they can be "aware" of the attributes and content of the mail that initiates the triggering.

The tasks configured demonstrate the following capabilities among others:

• Capability to trigger a task or a workflow based on received Emails.
• Propagation of useful information (like Email attributes) to downstream tasks.
• Availability of Email attachment on downstream tasks,

The components of the solution are described below:

1. "UC1: Send Email" - Send Email to a Mailbox using the Email Integration
2. "UC1: Monitor Email from Microsoft Server (Event Producer)" - Subscribes to Microsoft Server, monitors emails, saves attachments and emails on the Agent's filesystem and sends Universal Event for each monitored email.
3. "UC1: Universal Monitor: Wait for Email (Event Consumer)" - Monitors the Universal Events published from "UC1:  Monitor Email from Microsoft Server (Event Producer)"
4. "UC1: Trigger Workflow" - Triggers the configured workflow "UC1: Workflow Execution" when the Monitor condition on (3) is true.
5. "UC1: Print Event Attributes" - A task that is executed inside "UC1: Workflow Execution". Prints the Event Attributes which contain information from the Sent Email (1)
6. "UC1: Print Attachment Contents" - A task that is executed inside "UC1: Workflow Execution". Prints the Emails Attachment, if (1) is configured to have an attachment.

How to Run

Execution Steps:

• STEP 1: Enable Trigger "UC1: Trigger Workflow". This automatically starts "UC1: Universal Monitor: Wait for Email (Event Consumer)" and "UC1: Monitor Email from Microsoft Server (Event Producer)"
• STEP 2: Launch task "UC1: Send Email". By default, it does not point to an attachment but can be configured to do so. Repeat task multiple times. Workflow is triggered for each email monitored successfully.
• STEP 3: Review the outputs of "UC1: Print Event Attributes" & "UC1: Print Attachment Contents" task instances.

Expected Results:

• Mail is sent, successfully monitored and a workflow is launched.
• Tasks "UC1: Print Event Attributes" and "UC1: Print Attachment Contents" provide the required information from the originated Email.

Use Case 2: Approval Workflow via Email Notifications

Description

In this Use Case, emails are used as a mechanism for approval within an executed workflow. The user can make the approval, using only the mailbox application of choice. The tasks configured demonstrate the following capabilities among others:

• Capability to have an approval workflow via email notifications.
• Propagation of useful information (like Approval Reply Email body) to downstream tasks
• Move monitored emails to specific mailbox folder ("Archive" default email folder is used)

The components of the solution are better described through the workflow below:

1. "UC2: Create Attachment for Email Approval" - Creates a simple txt attachment on the Agent as a preparation step before the sending of the approval email.
2. "UC2: Send Approval Email" - Sends an approval Email.
3. "UC2: Universal Monitor: Wait for Approval Reply" - Monitors the Universal Events published from "UC2: Wait for Approval Reply". Task is running while waiting for the event to come. Note that when "UC2: Universal Monitor: Wait for Approval Reply" is started, the task "UC2: Wait for Approval Reply" is automatically started, which is responsible for Email Monitoring.
4. Then, the User using the mailbox application of choice performs the following steps:
   1. Receives an approval Email.
   2. Reviews the attachment and related content.
   3. Clicks on "Approve" or "Reject" button links. A preformatted email appears where user can add additional text as a reply. The content of this mail can be seen on (8) and (9)
   4. Sends the Email. 
5. "UC2: Wait for Approval Reply" detects the Approval Reply and sends a Universal Event to "UC2: Universal Monitor: Wait for Approval Reply". The monitor condition of "UC2: Universal Monitor: Wait for Approval Reply" is set to true and task instance gets completed, allowing for the resume of the workflow.
6. "UC2: Clean Temporary Attachments" -  Cleans up the temporary attachment that is created in (1).
7. "UC2: Approval or Rejection ?" - Task that exits with "0" in case of Approval, and exits with "1" in case of Rejection. Used to branch-out the workflow and have separate tasks for "Approval" or for "Rejection" 
8. "UC2: Actions when Approval Status = "Approved"" - A simple task that models the task that is run in case of "Approval". It prints approval status and the body of the mail related to the Approval Reply.
9. "UC2: Actions when Approval Status = "Rejected"" - A simple task that models the task that is run in case of "Approval". It prints approval status and the body of the mail related to the Rejection Reply.

How to Run

Execution Steps:

• STEP 1: Start workflow "UC2: Approval Workflow via Email Notifications"
• STEP 2: Notice that on the configured email address an Email Approval has been sent. For best results, use the preview pane to click the Approve/Reject links on the following step, as some mailbox applications restrict the usage of links in separate windows.
• STEP 3: Click "Approve" or "Reject". A preformatted mail appears. You can update the content of the mail providing some information and send the mail. Mail is sent, universal monitor after a while detects the Email approval reply and workflow is resumed until completion
• STEP 4: Review the STDOUT of tasks "UC2: Actions when Approval Status = "Approved"" or "UC2: Actions when Approval Status = "Rejected"" 

Expected Results:

• "UC2: Actions when Approval Status = "Approved"" or "UC2: Actions when Approval Status = "Rejected"" should reflect the approval status and body of the Email approval reply.

Input Fields

Output Fields

Email Monitor Events

Event Template: Email Monitor

Environment Variables

Environment Variables can be set from Environment Variables task definition table. The following environment variables can affect the behavior of the extension.

Exit Codes

STDOUT and STDERR

STDOUT of this integration is empty and STDERR provides additional information to the user, the detail of it is tuned by Log Level Task Definition field.

How To

Import Universal Template

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

1. This Universal Task requires the Resolvable Credentials feature. Check that the Resolvable Credentials Permitted system property has been set to true.

2. To import the Universal Template into your Controller, follow these instructions.

3. 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 /wiki/spaces/IS/pages/1394376723.

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.

Event Template configuration related to “Metric Label Attributes” & “Optional Metric Labels” is allowed. However, administrators should be cautious of high cardinality scenarios that might occur.

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

Document References

This document references the following documents:

Changelog

ue-email-monitor-1.0.0 (2025-05-29)

Initial Version