Using email attributes and filters¶
As shown earlier in the fetching email messages section, we can use different attributes in a filter when searching for some email messages.
Using the Microsoft Graph API, filters are based on Open Data Protocol (OData). The filter string allows us to create advanced filters by combining different attributes and operations.
In the examples below, we show some ways to create advanced filters and comparisons when directly using a filter string based on OData.
Building a filter string¶
Generally, the filter string is complex and can get confusing depending on the operations performed. Based on this, through the plugin, it is possible to create filters more simply through the Query class. In this way, we managed to create the same filter strings but more easily and intuitively.
To start building the filter string, let's use the Outlook plugin instance.
Using the new_query_filter method, we will obtain the Query object that will be used as a basis for building a new filter.
Using message attributes¶
This Query object allows us to define the attribute we intend to use in the filter; then, we can determine the operation that will be done considering this attribute.
We can, for example, search for an email with a specific subject or that contains certain content in the subject.
# Filter to search for all emails with the subject "Test Message"
query_filter.on_attribute("subject").equals("Test Message")
# Filter to search for all emails with "Test" in the subject
query_filter.on_attribute("subject").contains("Test")
# Filter considering only the address that sent the email
query_filter.on_attribute("from").equals("test@email.com")
Using multiple attributes in the filter¶
In addition to using attributes individually, it is also possible to combine multiple attributes into the same criteria string.
This would be equivalent to an AND operation. Only messages that match all filters will be returned.
It is also possible to do OR operations to filter messages by one attribute or another. In this case, use the chain method indicating the OR operator.
# Filter only messages that match one of these attributes:
#
# "Filter this message" as subject
# OR
# "Message to filter" as subject
query_filter = outlook.new_query_filter()
query_filter.on_attribute("subject").equals("Filter this message").chain("or").\
on_attribute("subject").equals("Message to filter")
Using the filter string when fetching messages¶
After building the filter string, just use it as a parameter of the search_messages method.
outlook = MS365OutlookPlugin(service_account=service)
# Creating a new filter through the Query object
query_filter = outlook.new_query_filter()
# Filter using email subject
query_filter.on_attribute("subject").equals("Test Message")
# Searching for all emails with the subject "Test Message"
messages = outlook.search_messages(criteria=query_filter)
# This same filter could also be written this way (OData)
messages = outlook.search_messages(criteria="subject eq 'Test Message'")
Comparing filter strings¶
At first, it might seem that strings in OData format are not confusing.
However, building the string this way may be unviable depending on the complexity and number of operations required in the filter.
The examples below show filters created using the guide above and the equivalent OData string version.
Tip
If you already use or are familiar with the Open Data Protocol (OData) pattern, you can continue building the filter strings this way without any problem.
The search_messages method also supports the filter string in this model as long as the syntax is correct.
The Query class is just a facilitator and a more practical way to create filters to search for specific messages.
- Filter using the email subject
- Filter using the address that sent the email
- Filter using multiple email attributes
- Filter performing an 'OR' operation
- Filters using email creation date
Tip
Using the created_date_time attribute, you can perform several operations using a specific date as a base.
You can create a filter to search for emails that were received on that date and on a date greater or lesser than that.
from datetime import datetime
...
# Searching for emails received on 04/26/2023
query_filter.on_attribute('created_date_time').equals(datetime(2023, 4, 26))
# Searching for emails with a date greater than or equal to 04/26/2023
query_filter.on_attribute('created_date_time').greater_equal(datetime(2023, 4, 26))
# Searching for emails with a date less than or equal to 04/26/2023
query_filter.on_attribute('created_date_time').less_equal(datetime(2023, 4, 26))
# Searching for emails received on 04/26/2023
"createdDateTime eq 2023-04-26T03:00:00+00:00"
# Searching for emails with a date greater than or equal to 04/26/2023
"createdDateTime ge 2023-04-26T03:00:00+00:00"
# Searching for emails with a date less than or equal to 04/26/2023
"createdDateTime le 2023-04-26T03:00:00+00:00"
Attribute table¶
See the table below for the most common attributes that can be used to construct filters using the Query object.
| Attribute | Description | Value type |
|---|---|---|
subject |
the email subject | str |
from |
the email sender's address | str |
created_date_time |
email date | date |
body |
contains the text in the email body | str |
isRead |
the email has the "read" flag or not | bool |