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: firstname.lastname@example.org messages = email.search('FROM "email@example.com"')
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 "firstname.lastname@example.org")' # 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: email@example.com # Marked as unseen attributes_search = '(SUBJECT "Test Mail") (FROM "firstname.lastname@example.org") (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:
|Attribute||Description||Type of value|
||with/without the Seen flag||str|
||contain specified str in envelope struct’s FROM field||str|
||contain specified str in envelope struct’s TO field||str|
||contain specified str in envelope struct’s CC field||str|
||contain specified str in envelope struct’s BCC field||str|
||contain specified str in envelope struct’s SUBJECT field||str|
||contain specified str in body of the message||str|
||internal date is within specified date||str|
||internal date is within or later than the specified date||str|
||internal date is earlier than the specified date||str|
See more details about the attributes that can be used in this link. Remember that all attributes are of type
str in the
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: email@example.com messages = email.filter_by(MailFilters.FROM, "firstname.lastname@example.org") # 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:
|Attribute||Description||Type of value|
||with/without the Seen flag||bool|
||address from email sender||str|
||address receiver as TO||str|
||address receiver as CC||str|
||address receiver as BCC||str|
||the email subject||str|
||contains the text in the email body||str|
||email date is within specified date||date|
||email date is within or later than the specified date||date|
||email date is earlier than the specified date||date|