Ir para o conteúdo

Usando atributos e filtros de e-mail

Conforme mostrado anteriormente na seção buscando algumas mensagens de email, podemos usar atributos diferentes em um filtro ao recuperar alguns e-mails.

Uma maneira de procurar emails usando filtros é através do método search, neste caso deve-se passar uma string completa referente ao critério a ser usado. Dessa forma, torna-se responsabilidade do usuário usar os atributos e a sintaxe corretamente.

# Procura todos os e-mails enviados pelo endereço: joao@email.com
messages = email.search('FROM "joao@email.com"')

Busca Avançada

Temos a possibilidade de criar buscas avançadas manualmente usando um único atributo ou combinando diferentes atributos.

Usando um único atributo

Basicamente, a estrutura da string de critérios é composta pelo nome do atributo em letras maiúsculas seguidas pelo valor do atributo entre aspas. Você também pode usar a string entre () para torná-la mais organizada.

Em geral, para cada atributo, a estrutura usada será algo assim: '(NOME_ATRIBUTO "valor_do_seu_atributo")'.

# Cria busca considerando apenas o assunto do e-mail
busca_assunto = '(SUBJECT "Mensagem de teste")'

# Procura todos os e-mails que têm "mensagem de teste" como assunto
busca_mensagens_1 = email.search(busca_assunto)

# Cria busca considerando apenas o endereço que enviou o e-mail
busca_from = '(FROM "test@email.com")'

# Procura todos os e-mails enviados a partir do endereço "test@email.com"
busca_mensagens_2 = email.search(busca_from)

Usando vários atributos

Além de usar atributos individualmente, também é possível combinar vários atributos na mesma sequência de critérios.

Basicamente, isso seria equivalente a uma operação AND. Somente mensagens que correspondem a todos os critérios serão retornadas.

# Busque apenas mensagens que correspondem a todos esses atributos:
# Assunto: "Teste E-mail"
# Enviado por: "test@email.com"
# Marcado como não lido
busca_atributos = '(SUBJECT "Teste E-mail") (FROM "test@email.com") (UNSEEN)'

mensagens = email.search(busca_atributos)

Também é possível fazer operações OR, para buscar mensagens por um atributo ou outro. Nesse caso, basta inserir OR no início da string e manter os critérios da mesma maneira.

# Busque apenas mensagens que correspondem a um desses atributos:
# Assunto: "Filtre esta mensagem"
#  OR
# Assunto: "Mensagem para filtrar"
busca_atributos = '(OR (SUBJECT "Filtre esta mensagem") (SUBJECT "Mensagem para filtrar"))'

mensagens = email.search(busca_atributos)

Veja na tabela atributos mais comuns utilizados no metodo search para criar strings de busca:

Atributo Descrição Tipo de valor
SEEN/UNSEEN com/sem a flag Visto str
FROM endereço do remetente do e-mail str
TO destinatário do endereço como TO str
CC destinatário de endereço como CC str
BCC destinatário do endereço como BCC str
SUBJECT o assunto do e-mail str
BODY contém o texto no corpo do e-mail str
ON a data do e-mail está dentro da data especificada str
SINCE a data do e-mail está dentro ou depois da data especificada str
BEFORE a data do e-mail é anterior à data especificada str

Dica

Veja mais detalhes sobre os atributos que podem ser usados neste link. Lembrando que no método search, todos atributos são do tipo str.

O método filter_by

Em alguns casos, o caminho acima pode ficar um pouco confuso ou gerar dúvidas ao construir a string do filtro. Portanto, é possível usar o método filter_by como um "atalho" para fazer os filtros.

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

# Você pode visualizar e selecionar um atributo usando: Mailfilters.<ATTRIBUTE_NAME>

# Procura todos os e-mails enviados pelo endereço: joao@email.com
mensagens = email.filter_by(MailFilters.FROM, "joao@email.com")

# Procura todos os e-mails que ainda não foram lidos
mensagens = email.filter_by(MailFilters.SEEN, False)

# Procura todos os e-mails recebidos na data: 15/02/2022
mensagens = email.filter_by(MailFilters.ON_DATE, datetime(2022, 2, 15).date())

Nesse caso, não é necessário se preocupar com a sintaxe da sequência do filtro, basta passar o atributo desejado no filtro e o valor que esse atributo deve ter.

Tabela de atributos do metodo filter_by

Os atributos que podem ser usados são definidos na classe MailFilters como uma enumeração, a tabela a seguir mostra os atributos definidos e que tipos de valores eles podem receber:

Atributo Descrição Tipo de valor
SEEN com/sem a flag Visto bool
FROM endereço do remetente do e-mail str
TO destinatário do endereço como TO str
CC destinatário de endereço como CC str
BCC destinatário do endereço como BCC str
SUBJECT o assunto do e-mail str
TEXT_CONTENT contém o texto no corpo do e-mail str
ON_DATE a data do e-mail está dentro da data especificada date
DATE_GREATER_THAN a data do e-mail está dentro ou depois da data especificada date
DATE_LESS_THAN a data do e-mail é anterior à data especificada date