Using email attributes and filters¶

As shown earlier in the fetching some email messages section, we can use different attributes in a filter when retrieving some emails.

The search method¶

A way to search for emails using filters is through the search method, in this case a complete string referring to the criterion to be used must be passed. This way makes it the user's responsibility to use the attributes and syntax correctly.

# Searches for all emails sending by the address: joao@email.com
messages = email.search('FROM "joao@email.com"')

Advanced Searching¶

With the possibility to build a search manually, we can create an advanced search using a single attribute or combining different attributes.

Using a single attribute¶

Basically the structure of the criteria string is composed by the attribute name in capital letters followed by the attribute value in quotes. You can also use the string between (), to make it more organized.

In general, for each attribute, the structure used will be something like this: '(ATTRIBUTE_NAME "value_for_this_attribute")'.

# search using email subject only
subject_search = '(SUBJECT "Test Message")'

# Searches for all emails that have "Test Message" as subject
messages_search_1 = email.search(subject_search)

# search considering only the address that sent the email
from_search = '(FROM "test@email.com")'

# Searches for all emails sent from this address
messages_search_2 = email.search(from_search)

Using multiple attributes¶

In addition to using attributes individually, it is also possible to combine multiple attributes into the same criteria string.

Basically, this would be equivalent to an AND operation. Only messages that match all criteria will be returned.

# Search only messages that match all of these attributes:
# 
# Subject: "Test Mail"
# Sent by: test@email.com
# Marked as unseen
attributes_search = '(SUBJECT "Test Mail") (FROM "test@email.com") (UNSEEN)'

messages = email.search(attributes_search)

It is also possible to do OR operations to search messages by some attribute. In this case, just insert OR at the beginning of the string and keep the criteria the same way.

# Search only messages that match one of these attributes:
# 
# Subject: "Search this message"
#  OR
# Subject: "Message to filter"
attributes_search = '(OR (SUBJECT "Search this message") (SUBJECT "Message to filter"))'

messages = email.search(attributes_search)

Table: search method attributes¶

See the table for the most common attributes used in the search method to create search strings:

The filter by method¶

In some cases, the way above can get a little confusing or generate doubts when building the filter string. Therefore, it is possible to use the filter_by method as a "shortcut" to make the filters.

from botcity.plugins.email import MailFilters
from datetime import datetime

# You can view and select an attribute using: MailFilters.<ATTRIBUTE_NAME>

# Searches for all emails sending by the address: joao@email.com
messages = email.filter_by(MailFilters.FROM, "joao@email.com")

# Searches for all emails that have not yet been read
messages = email.filter_by(MailFilters.SEEN, False)

# Searches for all emails that were received on the date: 15/02/2022
messages = email.filter_by(MailFilters.ON_DATE, datetime(2022, 2, 15).date())

In this case, it is not necessary to worry about the syntax of the filter string, just pass the desired attribute in the filter and the value that this attribute should have.

Table: filter_by method attributes¶

The attributes that can be used are defined in the MailFilters class as a Enum, the following table shows the attributes that are defined and what types of values they can receive: