Setting up an Email Trigger (SMTP) step


The Email Trigger (SMTP) is used to trigger a task based on the contents of incoming or outgoing mail sent via a virtual SMTP email server.

When an email is received it is compared against a number of filters created within the tool, any field of an email can have a filter placed against it such as the senders email address, the subject bar or the main body of the email.

If all filter requirements are met the message triggers a task to run. Information can be extracted from the email by using variables for use in later steps of the task.

Example: A trigger is setup to filter emails with the subject ‘Web Enquiry’, this is an email containing a set form requesting information on a product. The task is set in motion and variables are applied to extract which product the enquirer requires details about. A database query is completed using the product name and an email is sent to the appropriate product manager to deal with the request.


Before the Email Trigger (SMTP) tool can be used prerequisites have first got to be met. The user must have installed the ‘Email Trigger (SMTP) Agent’ on the same machine as the TaskCentre server. This ensures any email messages needed to trigger TaskCentre events are redirected to the Microsoft SMTP virtual server running on the TaskCentre server.

The Email Trigger (SMTP) tool has two modes of delivery which can be configured via the Email Trigger (SMTP) global configuration:

Manage -> Tools -> Event -> Email Trigger (SMTP)

Direct Delivery Mode (default): Email messages will be stored by the Email Trigger (SMTP) Tool and then passed immediately to the original recipient.

Mail Intercept Mode: Email messages are intercepted by the SMTP Virtual Server, handled by TaskCentre and then re-submitted to the recipient. This allows messages to be aborted by TaskCentre if required and therefore not delivered to the original recipient.

Note: To prevent delays in processing email messages if TaskCentre is running slowly, the default option is set to Direct Delivery Mode.

Using the Tool

Creating Variables

Before the Email Trigger (SMTP) tool is setup and if any key information is to be extracted from the email, variables have first got to be created to store this information. Variables are created in the Task Browser as follows:

  1. Select the Environments tab, locate the Variables node and right click to select New
    SMTP 2(1)
  2. The following box will be displayed. Provide an appropriate name for the variable and a description if required. Below is an example:
    SMTP 3
  3. Select the Details tab to display the Variable Properties:
    SMTP 4
  4. The variable is normally always created with the type being Variant, Parameter tick box should be selected and In, Out selected as the parameter attributes.
    • Having parameter selected allows the variable to have data mapped to it.
    • Array allows a variable to have a message attachment mapped to it when the type is set to Datafile. For further details on how a variable can save an email attachment please see the following article: Extract an email attachment and save to a location

    The Scope is normally set to Task Instance which means that data held in the variable only exists while this task is running. If Task is selected then the data held in the variable is persisted across different runs of the task.

    • Multiple variables can be created to store various types of key information for the task and are usually tailored around the task step they are to be used in.

Configuring the Email Trigger (SMTP) tool

The Email Trigger (SMTP) tool is dragged from the task browser under Event tools and into the task planner. This will automatically open the General tab where a name and description can be entered for the step.

SMTP 5(2)

Main Tab

The Main tab is used to create a filter which is placed on a specified mail server, variables are also mapped to parameters in the email. A task is triggered when an email matching the filter criteria is met and the variables extract key information.

Note: In the above screenshot, notice how any variables created in the task browser are loaded into the Email Trigger (SMTP) tool for use. By default they will be unmapped.

Use Agent – This drop down list is used to select a mail server.It displays a list of all mail servers that have the Mail Event Agent installed on them. Selecting a mail server means that only e-mails received by that server will be used to trigger a task. Alternatively, selecting the option All Mail Event Agents means that all mail servers listed will be used.

Filters – This area contains all active filters in place which are looking for specific criteria to trigger the task. Filters can be added, edited and removed.

Any of the above – Only emails received that match the criteria from any one of the filters will be used to trigger the task.

All of the above – Only emails received that match the criteria from all of the filters will be used to trigger a task.

Mapping – This area displays created task variables and is used to map the variables to parameter fields in the email. The Parameter column contains a drop down list where an email parameter can be selected. If a variable has the array option selected during creation, then it can be mapped to the message attachment field.

Mapping Parameters

1. Using the Parameter column click on (unmapped) to display a drop down list then map the variables to the required fields. This is telling the variable what information to store.


Creating a Filter

After the parameters have been mapped a filter needs to be created.

  1. Select Add to display the Filter Properties:SMTP 7
    Mail Property – This contains a drop down list and allows you to specify which field of an email to apply the filter to.
    Filter Mask – Specific text can be entered here which tells the filter what to search for.
    Case Sensitive Match – Selecting this option will allow the text search to be case sensitive.
  2. From the Mail Property drop down list select the required field to apply a filter to.
  3. In the Filter Mask text box specify what the filter is going to search for and decide if it needs to be a case sensitive match.
    SMTP 8
  4. Select OK to close. The created filter will now appear in the Filters area.SMTP 9

This completes configuring the Email Trigger (SMTP) tool.

To read about tasks which make use of this tool see:

Building a task which triggers when an email is received

Building a task which uses a decision step to control the task process flow