Email Trigger

Description

Monitors an email server for incoming or outgoing messages that meets certain rules or conditions and then triggers task execution when such conditions are met. With regular expressions, you can create filters that can match patterns of text rather than only single words or phrases.

Practical Usage

Ideal for automated execution of email-related operations. For example, this trigger can monitor incoming email messages from a particular email address. Upon receipt of that message, a particular email address, you can run a task that processes the information received in that email, generates a report based on the information, and emails the report to multiple colleagues.

Related Topics  

Parameters

General

Property Type Description
Protocol Options Specifies the protocol to use to connect to the email server. The available options are: The available options are:
  • WEBDAV (Exchange 2003, 2007) - Uses the Web Distributed Authoring and Provisioning (WEBDAV) protocol. Compatible with Microsoft Exchange Server 2003 and Exchange Server 2007.
  • EWS (Exchange 2007 & newer, Online) - Uses the Exchange Web Services (EWS) protocol. Compatible with Microsoft Exchange Server 2007 and newer versions, and Exchange Online.
  • EWS Online - Uses the EWS protocol to access Microsoft Exchange Online by way of Modern Authentication.
If the Protocol parameter is set to WEBDAV (Exchange 2003, 2007), refer to these parameters.
Email address Text A valid email address to use to authenticate the connection to the Exchange server.
Exchange server Text Specifies the address of the Exchange server. Select one of the following Exchange server protocol types:
  • HTTPS (default) - HTTP over SSL or HTTP Secure.
  • HTTP - HyperText Transfer Protocol.
Authentication type Options Specifies the type of authentication to use to connect to the Exchange server. The following options are:
  • Basic - Processes basic authentication credentials presented in HTTP headers.
  • Default - Authentication is through the stored Windows credentials of the current user. Selecting this option disables the Domain name, Username, and Password parameters.
  • Form - Authentication is forms-based which lets you use an HTML form to obtain credentials from users who are attempting to access the Exchange server.
Domain name Text The domain name (for example, domain.exchangeServer.com) or IP address to use to connect to the Exchange server. This parameter is available only if the Authentication type parameter above is set to Basic or Form.
Username Text A valid username to use to authenticate the connection to the Exchange server. This value may or may not be identical to the value set in the Email address field.
Password Text A valid password, corresponding to the Username parameter, to use to authenticate Exchange connection.
If the Protocol parameter is set to EWS (Exchange 2007 & newer, Online), refer to these parameters.
Email address Text A valid email address to use to authenticate the connection to the Exchange server. This email address can be used to discover the Exchange server to be entered in the Exchange server parameter below.
Username Text A valid username to use to authenticate the connection to the Exchange server.
Password Text A valid password, corresponding to the Username parameter, to use to authenticate Exchange connection.
Domain name (optional) Text The domain name (for example, domain.exchangeServer.com) or IP address to use to connect to the Exchange server. This parameter is optional.
Exchange server Text Specifies the address of the Exchange server. Select one of the following Exchange server protocol types:
  • HTTPS (default) - HTTP over SSL or HTTP Secure.
  • HTTP - HyperText Transfer Protocol.

After making a selection, click Discover to automatically discover the server based on the credentials entered for the Email address, Username, and Password parameters.

Authenticate as current Windows user Yes/No If selected, authentication to the Exchange server is by way of the current Windows user's credentials, and the Username, Password and Domain name parameters are disabled. This parameter is disabled by default.
If the Protocol parameter is set to EWS Online, refer to these parameters.
Email address Text A valid email address to use to authenticate the connection to the Exchange server.
Tenant ID Text The tenant ID to use for authentication. This parameter is encrypted in Task Builder.
Client ID Text The client ID to use for authentication. This parameter is encrypted in Task Builder.
Client secret Text The client secret to use for authentication. This parameter is encrypted in Task Builder. Once the Email address, Tenant ID, Client ID, and Client secret parameters are populated, click Verify to perform a test connection to the Exchange Online server.

General - Advanced

Property Type Description
Current folder path Text Specifies the current mailbox folder this trigger monitors. The value entered in this parameter corresponds directly with the filtering criteria you set by way of the Filter section below. For example, if your filter is set to monitor sent email to denote other Exchange well known folders (for example, Calendar, Drafts, Tasks, etc.), enter the Exchange property name for that folder. To specify subfolders, use a / character (for example, Inbox/SubFolderName). For more details on Exchange well known folders, see the Well-Known Mailbox Folders section below.
Impersonate Yes/No If selected, this parameter allows an account on an Exchange server to perform actions by using the permissions that are associated with another account, instead of the permissions that are associated with the caller's account. This parameter is cleared by default. This parameter is only available if the Protocol parameter is set to EWS (Exchange 2007 & newer, Online).
NOTE: With Exchange Impersonation, one account is acting as another account. When an account is impersonated, the system logs the access as if the account that is specified in the header were acting on the system. The calling account must have the appropriate permissions to perform impersonation.
Ignore invalid server certificate Yes/No If selected, invalid or expired SSL server certificates are ignored. If cleared (default) and an invalid server certificate is found, this step throws an error stating that the security certificate on the server is not valid. This parameter is only available if the Protocol parameter is set to EWS (Exchange 2007 & newer, Online).
Timeout (seconds) Number The period of time (in seconds) that will be allowed for a connection to be established before a timeout occurs.
Proxy type Options Specifies the proxy type for Automate to use when attempting network communications through a proxy server. The available options are:
  • None - Explicitly instructs the action not to use a proxy server regardless of the system default.
  • SOCKS 4 - Instructs the action to go through a SOCKS 4-compliant server.
  • SOCKS 4a - Instructs the action to go through a SOCKS 4a -compliant server.
  • SOCKS 5 - Instructs the action to go through a SOCKS 5-compliant server.
  • HTTP - Instructs the action to go through an HTTP-compliant server.
NOTE: If you are unsure of the value to use in this parameter, contact your network administrator.
Proxy server Text The hostname (server.domain.com) or IP address of the proxy server. This parameter is only available and required if the Proxy type parameter is set to SOCKS 4, SOCKS 4A, SOCKS 5, or HTTP.
Proxy port Number The proxy port number to use to connect to the proxy server. Most proxy servers operate on port 1028 ( default), however, a proxy server can operate on other ports. This parameter is only available and required if the Proxy type parameter is set to SOCKS 4, SOCKS 4A, SOCKS 5, or HTTP.
Proxy username (optional) Text The username to use to authenticate when connecting through the proxy server. This parameter is only available if Proxy type is set to SOCKS 5 or HTTP.
Proxy password(optional) Text The password used to authenticate the username entered in the Proxy username parameter. This parameter is only available if Proxy type is set to SOCKS 5 or HTTP.

Filter

Property Type Description
Select filtering criterias --- Denotes specific email rules or criteria to activate the trigger. Email filters use the criteria specified for incoming or outgoing email to determine task triggering. The first part examines the field name and value to determine whether they match your filter parameters. The second part uses relational operators to determine the type of comparison used to compare that portion of the email message based on the operator that you select. When two or more filters are applied, Automate uses the AND logic and all conditions must return TRUE in order to activate the trigger.

Click Add, Edit, or Remove to manage filtering criteria.
Field Name Text The field name of the email message to monitor. This parameter corresponds with the Operator and Field Value parameters to determine a match. The available options are:
  • From - The email address used to send the message.
  • To - The primary email addresses the message was sent to.
  • CC - The email addresses that were copied on the message.
  • Subject - The subject line of the message.
  • Body - The body of the message.
  • Date - The date the message was sent or received.
  • Time - The time the message was sent or received.
  • Attachment Name - The name of the attachment included with the message.
  • Attachment Extension - The file extension of the attachment (for example, .pdf or .txt).
  • Attachment Size - The file size of the attachment.
  • Attachment Count - The total number of attachments included with the message.
Operator Options Displays relational operators that can be used to find the relation between two operands by comparing their values. All of the relational operators result in a Boolean (TRUE/FALSE) value. This parameter is combined with the Field Name and Field Value parameters to form a complete filter. The available operators compatible with this trigger are:
  • = - Examines if the values of two operands are equal. If the values are equal, then the condition returns TRUE.
  • != - Examines if the values of two operands are not equal. If the values are not equal, then the condition returns TRUE.
  • Contains - Examines if a character or string is contained in a text field. If yes, then the condition returns TRUE.
  • !Contains - Examines if a character or string is not contained in a text field. If the character or string is not contained in the text field , then the condition returns TRUE.
Field Value Options The value of the field name to monitor. This parameter corresponds with the Field Name and Operator parameter to determine a match.

Behavior

Property Type Description
Enable trigger Yes/No If selected, the trigger activates upon creation, allowing it to immediately monitor the status for any defined conditions. If this parameter is cleared, the trigger stays inactive after creation and must be manually selected by the user in order to monitor defined conditions. This parameter is selected by default.
Trigger on startup if condition is true Yes/No If selected, the system reacts to conditions that already exist upon startup (that is, when the Automate Enterprise service starts, when global triggering is turned on, or when the specified workflow is re-enabled). This option is selected by default.
Trigger after the condition has been met 'X' times. Yes/No If selected, the system continues to wait until the monitored condition has transpired the specified amount of times. For example, if a Process trigger is set to wait for the Notepad process to start and this parameter is set to 3, the task will not launch until the third instance of the Notepad process starts.

Additional Notes

Well-Known Mailbox Folders

Each user's mailbox folder has a set of properties that you can use to retrieve well-known folders, such as Inbox, Calendar, Drafts, and Tasks. Specifying a subfolder requires first specifying the name of the folder from the well-known folders level as the parent folder, followed by a / character as the delimiter, and then the subfolder name (for example, Inbox/SubFolderName). To specify a folder that you created in the well-known folders level, you must specify the root of the message folder hierarchy (for example, MsgFolderRoot/SubFolderName). The table below defines common folder names (in alphabetical order) that are used in users mailboxes.

Name Description
ArchiveDeletedItems The Deleted Items folder in the archive mailbox.
ArchiveMsgFolderRoot The root of the message folder hierarchy in the archive mailbox.
ArchiveRecoverableItemsDeletions The root of the folder hierarchy of recoverable items that have been soft-deleted from the Deleted Items folder of the archive mailbox.
ArchiveRecoverableItemsPurges The root of the hierarchy of recoverable items that have been hard-deleted from the Deleted Items folder of the archive mailbox.
ArchiveRecoverableItemsRoot The root of the Recoverable Items folder hierarchy in the archive mailbox.
ArchiveRecoverableItemsVersions The root of the Recoverable Items versions folder hierarchy in the archive mailbox.
ArchiveRoot The root of the folder hierarchy in the archive mailbox.
Calendar The Calendar folder.
Contacts The Contacts folder.
DeletedItems The Deleted Items folder.
Drafts The Drafts folder.
Inbox The Inbox folder.
Journal The Journal folder.
JunkEmail The Junk email folder.
MsgFolderRoot The root of the message folder hierarchy.
Notes The Notes folder.
Outbox The Outbox folder.
PublicFoldersRoot The root of the Public Folders hierarchy.
RecoverableItemsDeletions The root of the folder hierarchy of recoverable items that have been soft-deleted from the Deleted Items folder.
RecoverableItemsPurges The root of the folder hierarchy of recoverable items that have been hard-deleted from the Deleted Items folder.
RecoverableItemsRoot The root of the Recoverable Items folder hierarchy.
RecoverableItemsVersions The root of the Recoverable Items versions folder hierarchy in the archive mailbox.
Root The root of the mailbox.
SearchFolders The Search Folders folder, also known as the Finder folder.
SentItems The Sent Items folder.
Tasks The Tasks folder.
Voicemail The Voicemail folder.

AMTrigger

When this trigger is activated, it automatically passes the AMTrigger object to the task. AMTrigger is a standard Automate dataset and can be used much like the datasets created by the Database - SQL query activity and Email action. The fields of AMTrigger can be used within a task to determine specific values, such as whether or not the task was started by a trigger, which trigger started the task, when the trigger was activated and other properties. AMTrigger populates a unique set of field–value pairs for each Automate trigger. The following table lists the ones specific to this trigger. For more details about a specific AMTrigger field–value pair, click the associated link.

Name Data Type Return Value
AMTrigger.MessageID String Returns the ID of the email message received or sent.
AMTrigger.ProtocolType String Returns the protocol type used to receive or send the email message.
AMTrigger.CurrentFolder String Returns the current mailbox folder used with this trigger.
NOTE: A full list of AMTrigger objects exclusive to each trigger can be viewed from the Expression Builder by expanding Objects > Triggers and selecting the desired trigger.