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.

Only for version 21.0.7-IF001, this command is also used to search in shared mailboxes that the connection's account have access to. Exchange and Outlook Desktop application connections use the Search in Mailboxes (N/A for IMAP) parameter to filter from 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)

Dependencies

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 collection 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 for more details.
Search Public Folders searchpublicfolders Optional Boolean Enable to add public folders to the search filter.
Search in Mailboxes (N/A for IMAP) searchsharedmailboxes Optional Text, List<Text> Only for version 21.0.7-IF001, the shared mailbox to be accessed. 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 must be included in the subject of the emails searched. This parameter is case-insensitive.

Due to a Microsoft™ server-side issue when using IMAP connections on versions before 23.0.1, this parameter behaves case-sensitively, capitalized words cause the filters to fail even when included in the search.

⚠ 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 cannot be included in the subject of the emails searched.

Due to a Microsoft™ server-side issue when using IMAP connections on versions before 23.0.1, this parameter behaves case-sensitively, capitalized words cause the filters to fail even when included in the search.

⚠ 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.

Due to a Microsoft™ server-side issue when using IMAP connections on versions before 23.0.1, this parameter behaves case-sensitively, capitalized words cause the filters to fail even when included in the search.

⚠ 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.

Due to a Microsoft™ server-side issue when using IMAP connections on versions before 23.0.1, this parameter behaves case-sensitively, capitalized words cause the filters to fail even when included in the search.

⚠ 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 When enabled, it searches only for emails containing attachments in the message.
Start Date startdate Optional Date Time Initial date filter from which emails will be fetched. Dates should be in UTC format.
End Date enddate Optional Date Time Final date filter from which emails will be fetched. Dates should be in UTC format.
Categories labels Optional List<Text> Definition of the email categories External link .

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 *, 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 mailbox.
  • If you want to filter from specific shared mailboxes, you must add their account email in a List<Text> variable, the filters are also applied to the default account mailbox.

Exchange connections

  • If you want to filter from specific shared mailboxes that your account has access to, you must add the shared mailboxes accounts email in a List<Text> variable, the filters are also applied to the default account mailbox.
  • If you leave it blank, the filters are applied only to the default account mailbox.

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 specify * 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.

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 Finds subjects containing all the words.
Any Any Finds 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 Finds text in the email body containing all the words.
Any Any Finds text in the email body containing one or more words from the list.

Example

The Apply Search Filters command uses the search filter to find all emails that contain 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 --usessl--username "useremail@email.com" --mailusername "useremail@email.com" --mailpassword userpassword --enableLogImapConnection=value
emailApplySearchFilters --searchallemails--from ${sender} --to ${recipient} --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.