Uso de atributos y filtros de correo electrónico¶

Como se mostró anteriormente en la sección obteniendo algunos mensajes de correo electrónico, podemos utilizar diferentes atributos en un filtro al recuperar algunos correos electrónicos.

El método search¶

Una forma de buscar correos electrónicos utilizando filtros es a través del método search, en este caso se debe pasar una cadena completa que se refiera al criterio a utilizar. De esta manera, es responsabilidad del usuario utilizar los atributos y la sintaxis correctamente.

# Busca todos los correos electrónicos enviados por la dirección: joao@email.com
mensajes = email.search('FROM "joao@email.com"')

Búsqueda avanzada¶

Con la posibilidad de construir una búsqueda manualmente, podemos crear una búsqueda avanzada utilizando un solo atributo o combinando diferentes atributos.

Utilizando un solo atributo¶

Básicamente, la estructura de la cadena de criterios está compuesta por el nombre del atributo en letras mayúsculas seguido del valor del atributo entre comillas. También se puede utilizar la cadena entre (), para que sea más organizada.

En general, para cada atributo, la estructura utilizada será algo como esto: '(NOMBRE_DEL_ATRIBUTO "valor_para_este_atributo")'.

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

Utilizando múltiples atributos¶

Además de utilizar atributos individualmente, también es posible combinar múltiples atributos en la misma cadena de criterios.

Básicamente, esto sería equivalente a una operación AND. Solo se devolverán los mensajes que cumplan con todos los criterios.

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

También es posible realizar operaciones OR para buscar mensajes por algún atributo. En este caso, simplemente inserta OR al principio de la cadena y mantén los criterios de la misma manera.

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

Tabla: atributos del método search¶

Consulta la tabla de los atributos más comunes utilizados en el método search para crear cadenas de búsqueda:

El método filter_by¶

En algunos casos, la forma anterior puede resultar un poco confusa o generar dudas al construir la cadena de filtro. Por lo tanto, es posible utilizar el método filter_by como un "atajo" para crear los filtros.

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

En este caso, no es necesario preocuparse por la sintaxis de la cadena de filtro, simplemente pasa el atributo deseado en el filtro y el valor que este atributo debe tener.

Tabla: atributos del método filter_by¶

Los atributos que se pueden utilizar están definidos en la clase MailFilters como un Enum, la siguiente tabla muestra los atributos que están definidos y qué tipos de valores pueden recibir: