Introduction to the Email Trigger (SMTP) Tool
What is an event triggered email (SMTP) tool?
The Email Trigger (SMTP) tool triggers a task to run based on the contents of incoming or outgoing mail sent via an SMTP mail server.
When an email is received, it is compared against a number of filters created in the step, defining values for the message parameters. When all filter requirements are met, the task is triggered. On receipt, each of the email parameters is exposed and their values may be mapped to variables created for the task and then used in other steps.
For example, a Task is created to monitor for email messages received from any of the Sales team for a specific product and then to supply the information directly to the appropriate Product Manager.
Video Overview
White Paper - Email Trigger (SMTP)
Event Triggered Email (SMTP) Tool Features
- Create filters for any message parameter
- Include multiple filters in a step
- Map message parameters to task variables for use in other steps
- Map message attachments to a variable array
Technical Summary
Working with other Steps
The Email Trigger (SMTP) tool is independent of any other steps used in a task. It does not directly consume objects outputted by other task steps, nor does it expose objects that can be directly consumed by other task steps. However, Email Trigger (SMTP) data is mapped to task variables which can be used by subsequent task steps.
Dependencies
The following products, technologies, protocols, or systems are required by the Email Trigger (SMTP) tool:
- SMTP Server — Installed from Windows Server Manager, this is a required dependency no matter what type
of SMTP server you are monitoring emails from - Email Trigger (SMTP) Agent — The Email Trigger (SMTP) Agent must be installed and registered on the same machine as the SMTP server
About the Email Trigger (SMTP) Event Agent
The Email Trigger (SMTP) Agent works with the Email Trigger (SMTP) tool to process incoming SMTP messages. It can run on the same or separate computer to the server. It launches tasks when messages arrive that match filter rules previously configured within a Email Trigger (SMTP) step for a task.
The Email Trigger (SMTP) Event Agent consists of two main components:
- IIS Event Sink
This component sits within the process space of the Microsoft SMTP Virtual Server and accepts messages as they are submitted to the engine. The messages are then passed directly to the Email Trigger (SMTP) Event Agent Service to be processed. - Email Trigger (SMTP) Event Agent Service
This component runs as a Service and accepts messages from the IIS Event Sink component. As messages are received the component examines the configured events in the system and runs Tasks as required.
Choosing the Email Delivery Mode
Before being used in a task step, you can change how the Email Trigger (SMTP) tool checks and stores the email for the trigger properties:
- All messages received by the SMTP Virtual Server are sent to the Email Trigger (SMTP) Agent for processing before being sent to the intended recipient (Direct Delivery Mode, default behaviour). To the user, this appears to be a normal, direct delivery service.
- All messages received by the SMTP Virtual Server are sent to the Email Trigger (SMTP) Agent for processing. You can then choose to forward the message to the intended recipient or abort the message. This is particularly useful where the recipient email address does not have an actual mailbox. (Mail Intercept Mode)
You set this in the Email Trigger (SMTP) Configuration window, which you launch by either: You open this window from the resources tree — expand System > Tools > Event and double-click Email Trigger (SMTP) in the items list.
Step Configuration
Email Trigger (SMTP) steps triggers a task to run when an email is sent or received containing specific parameter values. These parameter values can be taken from either in the Sent From, To Recipients, Cc Recipients, Subject, or Body Text sections of the email.
In addition, global variables created for the task may be mapped to the message parameters so that their values may be used in other steps. For example, a variable called Message could be mapped to the Body Text variable and then included in an SMS text message created using the Send Text Message step.
To add a new Email Trigger (SMTP) step to an existing task, you either:
- Click and drag the Email Trigger (SMTP) icon from the Task Browser to the task Design area.
- From the task’s Design tab, right-click on empty space and select New > Event > Email Trigger (SMTP).
For a detailed description of how to create new tasks, refer to the product help.
About the General Tab
- Name — Enter a meaningful name for the stepTIP: If this task instance makes use of two or more Email Trigger (SMTP) steps, ensure the Name used is unique for each individual step.
- Description — If required, enter a description of this step
About the Main Tab
You use the Main tab to configure the trigger that activates this task.
- Use Agent — Select the relevant Email Trigger (SMTP) Agent which is handling the emails for this task. Alternatively, choose All Email Trigger (SMTP) Agents to trigger on emails from all monitored SMTP servers.
- Filters — Add those filters which trigger this task to run. If adding multiple filters, you can choose to trigger the task when:
- Any of the above filter criteria are matched in an email
- All of the above filter criteria are matched, that is, a received email must “tick all the boxes”
Click Add to add a new filter
- Mapping — Prior to creating the Email Trigger (SMTP) task step, task parameter variables should have been created to store extracted email data. These are displayed in the Mapping table for use in this task step. You can map the available, required variables to the following Parameters:
- (unmapped) — Leave a variable as (unmapped) to not include it in this task step
- Sent From — Maps the variable to the email sender
- To Recipients — Maps the variable to the email recipients (“To” property only)
- CC Recipients — Maps the variable to the copied recipients (“CC” property only)
- Subject — Maps the variable to the email subject
- Body Text — Maps the variable to the email body
- HTML Body — If processing an HTML email, maps the variable to email body
- RFC822 Message — If processing a MIME email (message content type), maps the variable to the email body
- Message ID — Maps the variable to the ID in the email header
- Received Headers — Maps the variable to the email headers
- Sent On — Maps the variable to date the email was sentTIP: In order to view this property formatted as a date / time stamp, you must consume this variable in a Run VBScript step first to convert it, for example:
ThisStep.LogInfo CDate(Variables(")")) - Attachment — You can only map task variables that have an ArrayType to email attachments
Filter Properties
Use Filter Properties to add those email filters which cause this task step to run.
You can filter emails based on the following email properties (Mail Property):
- Sent From — Who sent the email; use wildcards (*) to filter on email domain, for example,
*@codelessplatforms.com - To Recipients — The email recipient (“To” address only)
- CC recipients — The copied in recipients (“CC” address only)NOTE: Avoid filtering emails based on a specific, full email address. This is because IIS uses the full display name as well as the email address, both encapsulated in parenthesis. We recommend the use of wildcards in such scenarios.
- Subject — The email subject line
- Body Text — The email body
- Attachment Filename — The filename of any email attachments
- HTML body — If processing HTML emails, the email body
- Message ID — The ID in the email header
- Received Headers — The headers contained in the email envelope
Add the filters to Filter Mask. If required, enable Case Sensitive Match to make the filter case-sensitive.
About the Options Tab
The Options tab allows you to define how errors in this step are handled at task runtime.
The Message Abort Options pane is only available when Mail Intercept Mode is selected in the global configuration. When operating in this mode, you can choose to abort the original message:
- Never — The message is never aborted and is always delivered to the original recipient
- Always — The message is always aborted and is never delivered to the original recipient
- On Fail — If the filter conditions set in the Main tab are not met, then the message is delivered to the original recipient
- On Success — If the filter conditions are met, then the message is never delivered to the original recipient Irrespective of the chosen email delivery mode, you can choose to send an email notification to nominated persons on receipt of an error (enable Send Error Notification To). You can also choose to attach the email that caused the error if available (enable Attach Original Message to Error Notification).
The types of errors that can cause a notification include: - Unable to read mappings
- Unable to extract message properties
- Unable to extract attachments
- Unable to open the requested task item to run
- Failed to get task variable
- Email Trigger (SMTP) Agent licence expired
- Unable to queue new mail event task
