Skip to content

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.

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")

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.

# Filter only messages that match all of these attributes:
# 
# "Test Message" as subject
# Sent by: test@email.com
query_filter = outlook.new_query_filter()

query_filter.on_attribute("subject").equals("Test Message").on_attribute("from").equals("test@email.com")

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
query_filter.on_attribute("subject").contains("Test Message")

"contains(subject, 'Test Message')"
  • Filter using the address that sent the email
query_filter.on_attribute("from").equals("test@email.com")

"from/emailAddress/address eq 'test@email.com'"
  • Filter using multiple email attributes
query_filter.on_attribute("subject").equals("Test Message").on_attribute("from").equals("test@email.com")

"subject eq 'Test Message' and from/emailAddress/address eq 'test@email.com'"
  • Filter performing an 'OR' operation
query_filter.on_attribute("subject").equals("Filter this message").chain("or").\
             on_attribute("subject").equals("Message to filter")

"subject eq 'Filter this message' or subject eq 'Message to filter'"
  • 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