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