Apply Search Filters

Apply filters to the connected email to search for specific messages.

Command availability: IBM RPA SaaS and IBM RPA on premises

Description

Apply filters to the connected email to search for specific messages.

This command is also used to search in shared mailboxes that the connection's account have access to. Exchange, Outlook Desktop application, and Microsoft™ Outlook connections use the Search in Mailboxes (N/A for IMAP) parameter to filter from shared mailboxes. It is also possible to apply the search filters only to shared mailboxes.

Script syntax

IBM RPA's proprietary script language has a syntax similar to other programming languages. The script syntax defines the command's syntax in the script file. You can work with this syntax in IBM RPA Studio's Script mode.

emailApplySearchFilters [--searchsharedmailboxes(List<String>)] --folderpath(String) [--searchpublicfolders(Boolean)] [--from(List<String>)] [--to(List<String>)] [--cc(List<String>)] [--bcc(List<String>)] [--subjectdirective(EmailStringFilterDirective)] [--inclusivesubject(List<String>)] [--exclusivesubject(List<String>)] [--wordsdirective(EmailStringFilterDirective)] [--inclusivewords(List<String>)] [--exclusivewords(List<String>)] [--withattachment(Boolean)] [--startdate(DateTime)] [--enddate(DateTime)] [--labels(List<String>)] --connection(EmailConnection) [--searchonlymailboxes(Boolean)]

Dependencies

Use the For Each (forEach) command to get email message instances. Otherwise, the command will only return the first result.
Use the following commands to connect to an email server:
- Connect to Exchange Email Server (exchangeConnect)
- Connect to IMAP Email Server (imapConnect)
- Connect to Outlook Server (outlookConnect)

Input parameters

The following table displays the list of input parameters available in this command. In the table, you can see the parameter name when working in IBM RPA Studio's Script mode and its Designer mode equivalent label.

Designer mode label	Script mode name	Required	Accepted variable types	Description
Connection	`connection`	`Required`	`Email Connection`	Variable with the connection that contains the email messages to apply the search filter.
Folder Name	`folderpath`	`Optional`	`Text`	Name of a specific folder on the email server to search with the filter. See the `folderpath` parameter options for more details.
Search in Mailboxes (N/A for IMAP)	`searchsharedmailboxes`	`Optional`	`Text, List<Text>`	The name of the shared mailbox that you want to access. See the `searchsharedmailboxes` parameter for more details.
From	`from`	`Optional`	`List<Text>`	Sender's email address.
To	`to`	`Optional`	`List<Text>`	Recipient's email address.
Cc	`cc`	`Optional`	`List<Text>`	Email addresses to which copies are to be sent.
Bcc	`bcc`	`Optional`	`List<Text>`	Email addresses to which blind copies should be sent.
Word Search Directive	`subjectdirective`	`Optional`	`EmailStringFilterDirective`	Option with rules for how words are searched in the subject of the email. See the `subjectdirective` parameter options for more details.
Inclusive Words in the Subject	`inclusivesubject`	`Optional`	`List<Text>`	Words that the filter searches for on emails. Up to version 23.0.1, this parameter behaved case-sensitively, capitalized words would cause the filters to fail. Scripts that use this parameter assuming it is case-sensitive might stop getting the expected response. Attention:If the filters are applied to texts that contain characters not listed in the US ASCII Character Set 🡥, the response might differ from what is expected to be filtered.
Exclusive Words in the Subject	`exclusivesubject`	`Optional`	`List<Text>`	Words that the filter exclude when searching for emails. Up to version 23.0.1, this parameter behaved case-sensitively, capitalized words would cause the filters to fail. Scripts that use this parameter assuming it is case-sensitive might stop getting the expected response. Attention:If the filters are applied to texts that contain characters not listed in the US ASCII Character Set 🡥, the response might differ from what is expected to be filtered.
Search Words in the Email Body	`wordsdirective`	`Optional`	`EmailStringFilterDirective`	Option with rules for how words are searched in the body of the email. See the `wordsdirective` parameter options for more details.
Inclusive Words	`inclusivewords`	`Optional`	`List<Text>`	Words that must appear in the body of the emails searched. Up to version 23.0.1, this parameter behaved case-sensitively, capitalized words would cause the filters to fail. Scripts that use this parameter assuming it is case-sensitive might stop getting the expected response. Attention:If the filters are applied to texts that contain characters not listed in the US ASCII Character Set 🡥, the response might differ from what is expected to be filtered.
Exclusive Words	`exclusivewords`	`Optional`	`List<Text>`	Words that cannot appear in the body of emails. Up to version 23.0.1, this parameter behaved case-sensitively, capitalized words would cause the filters to fail. Scripts that use this parameter assuming it is case-sensitive might stop getting the expected response. Attention:If the filters are applied to texts that contain characters not listed in the US ASCII Character Set 🡥, the response might differ from what is expected to be filtered.
Contains Attachment	`withattachment`	`Optional`	`Boolean`	Enable to search only for emails containing attachments in the message.
Start Date	`startdate`	`Optional`	`Date Time`	Start date to fetch the emails. Dates must be in UTC format.
End Date	`enddate`	`Optional`	`Date Time`	End date to fetch the emails. Dates must be in UTC format.
Categories	`labels`	`Optional`	`List<Text>`	The category of the emails. See Use categories 🡥 for more instructions about email categories.
Search only on Shared Mailboxes	`searchonlymailboxes`	`Optional`	`Only visible when the searchsharedmailboxes parameter is filled`	Enable to apply the search filters only to shared mailboxes.

Obsolete input parameters

The following table displays the obselete input parameters in this command. In the table, you can see the parameter name when working in IBM RPA Studio's Script mode and its Designer mode equivalent label, in which version it was obsoleted, and the command's behavior on versions up to the version it was obsoleted.

Designer mode label	Script mode name	Version	Description
Search Public Folders (Obsolete)	`searchpublicfolders`	`23.0.1`	Enable to add public folders to the search filter.

`searchsharedmailboxes` parameter options

The searchsharedmailboxes parameter is where you specify the shared mailbox or mailboxes you want the filters to be applied to. It behaves as follows:

Outlook Desktop application

If you enter an asterisk (*), the filter is applied to all folders of all shared mailboxes that the account has access to.
If you leave it blank, the filters are applied only to the default account's mailbox.
If you want to filter from specific shared mailboxes, you must add their account's email in a List<Text> variable. The filters are also applied to the default account's mailbox if the Search only on Shared Mailboxes parameter is not enabled.

Exchange connection and Microsoft™ Outlook email connection

If you leave it blank, the filters are applied only to the default account's mailbox.
If you want to filter from specific shared mailboxes, you must add their accounts's email in a List<Text> variable. The filters are also applied to the default account's mailbox if the Search only on Shared Mailboxes parameter is not enabled.

`folderpath` parameter options

The folderpath parameter is where you specify the folder you want the filters to be applied to. It behaves as follows:

If you enter an asterisk (*) on the folder name parameter, the filter is applied to all folders.
For IMAP and Outlook connections, if you leave it blank, the filter is applied to the default folder, which is the Inbox folder.
If you specify a folder name, the filters are applied to the specified folder.
For Exchange connections, if you leave it blank, the filters are applied to all folders.
You must reference subfolders by using the slash (/). For example, folder1/subfolder1/another_subfolder1.
For Outlook, you must still use Inbox if you want to reference the Inbox folder even if your Outlook application is in a language other than English.

`subjectdirective` parameter options

The following table displays the options available for the subjectdirective input parameter. The table shows the options available when working in Script mode and the equivalent label in the Designer mode.

Designer mode label	Script mode name	Description
All	`All`	Searches for subjects containing all the words from the list.
Any	`Any`	Searches subjects containing one or more words from the list.

`wordsdirective` parameter options

The following table displays the options available for the wordsdirective input parameter. The table shows the options available when working in Script mode and the equivalent label in the Designer mode.

Designer mode label	Script mode name	Description
All	`All`	Searches for a text in the email body containing all the words from the list.
Any	`Any`	Searches texts in the email body containing one or more words from the list.

Example

Example 1: The Apply Search Filters command uses the search filter to find all emails in the Inbox folder that contains an attachment.

defVar --name ImapConnection --type EmailConnection
defVar --name emailMessages --type EmailMessage
defVar --name sender --type List --innertype String --value "[useremail@email.com]"
defVar --name recipient --type List --innertype String --value "[recipientemail@email.com]"
defVar --name emailSubject --type String
defVar --name emailBody --type String
// Connects to the Outlook365 Imap server.
imapConnect --mailhost "outlook.office365.com" --mailport 993 --authenticationtype "BasicAuthentication" --mailusername "useremail@email.com" --mailpassword userpassword ImapConnection=value
emailApplySearchFilters --subjectdirective "All" --wordsdirective "All" --withattachment  --connection ${ImapConnection}
foreach --collection "${ImapConnection}" --variable "${emailMessages}"
	emailRead --message ${emailMessages} emailSubject=subject emailBody=body
endFor
emailDisconnect --connection ${ImapConnection}
// A filter is applied to search only emails that contain an attachment, to read them.

Note:Use a valid email connection to run this example script.

Example 2: The following example demonstrates how to apply the search filters only on shared mailboxes, ignoring the default email account. The command establishes a connection with a Outlook account, apply the filters only on shared mailboxes, and read the filtered emails.

defVar --name outlookConnection --type EmailConnection
defVar --name emailMessages --type EmailMessage
defVar --name sender --type List --innertype String --value "[useremail@email.com]"
defVar --name recipient --type List --innertype String --value "[recipientemail@email.com]"
defVar --name emailSubject --type String
defVar --name emailBody --type String
defVar --name sharedMailbox --type List --innertype String
// Connects to the Outlook server.
microsoftMailConnect --connection "${outlookConnection}"
// Apply search filters only to shared mailboxes, ignoring the default account.
emailApplySearchFilters --searchsharedmailboxes "${sharedMailbox}" --from ${sender} --to ${recipient} --subjectdirective "All" --wordsdirective "All" --connection ${outlookConnection} --searchonlymailboxes
// Read all the filtered emails.
foreach --collection "${outlookConnection}" --variable "${emailMessages}"
	emailRead --message ${emailMessages} emailSubject=subject emailBody=body
endFor
emailDisconnect --connection ${outlookConnection}

Note:Use a valid email connection to run this example script.

Example 3: In this example, the command uses the search filter to find all emails sent in January of 2023, from a specific sender to a specific recipient that contains an attachment.

defVar --name ImapConnection --type EmailConnection
defVar --name emailMessages --type EmailMessage
defVar --name sender --type List --innertype String --value "[useremail@email.com]"
defVar --name recipient --type List --innertype String --value "[recipientemail@email.com]"
defVar --name emailSubject --type String
defVar --name emailBody --type String
defVar --name startDate --type DateTime --value "2023-01-01 00:00:00"
defVar --name endDate --type DateTime --value "2023-01-31 00:00:00"
// Connects to the Outlook365 Imap server.
imapConnect --mailhost "outlook.office365.com" --mailport 993 --authenticationtype "BasicAuthentication" --mailusername "useremail@email.com" --mailpassword userpassword ImapConnection=value
emailApplySearchFilters --folderpath "*" --from ${sender} --to ${recipient} --subjectdirective "All" --wordsdirective "All" --withattachment  --startdate "${startDate}" --enddate "${endDate}" --connection ${ImapConnection}
foreach --collection "${ImapConnection}" --variable "${emailMessages}"
	emailRead --message ${emailMessages} emailSubject=subject emailBody=body
endFor
emailDisconnect --connection ${ImapConnection}
// A filter is applied to search only emails that contain an attachment, to read them.

Note:Use a valid email connection to run this example script.

Apply Search Filters

Description

Script syntax

Dependencies

Input parameters

Obsolete input parameters

searchsharedmailboxes parameter options

folderpath parameter options

subjectdirective parameter options

wordsdirective parameter options

Example

Related links

`searchsharedmailboxes` parameter options

`folderpath` parameter options

`subjectdirective` parameter options

`wordsdirective` parameter options