Google - Gmail¶
Interaja e execute várias operações por meio de uma conta do Google. Envie, recupere e responda às mensagens de e-mail facilmente através do plugin BotCity para o Gmail.
Instalação¶
Importando o Plugin¶
Depois de instalar este pacote e obter o arquivo de credenciais Google, a próxima etapa é importar o pacote para o seu código e começar a usar as funções.
Configurando o e-mail¶
Primeiro, vamos configurar a conta do Gmail e as credenciais que usaremos no código.
Informação
Sua conta do Gmail deve ser a mesma usada para gerar as credenciais.
Procurando por algumas mensagens¶
Com a conta devidamente configurada, vamos filtrar e buscar alguns e-mails.
# Busque todos os e-mails com o assunto: Hello World
mensagens = gmail.search_messages(criteria="subject:Olá Mundo!")
# Para cada email encontrado: imprime o assunto, endereço do remetente e conteúdo de texto do email
for msg in mensagens:
print("\n----------------------------")
print("Assunto => " + msg.subject)
print("De => " + msg.from_)
print("Msg => " + msg.text)
Neste exemplo, apenas o atributo subject (assunto) foi usado como filtro. No entanto, a API do Gmail oferece diferentes possibilidades, usando outras combinações e operadores. Veja mais detalhes sobre os operadores de pesquisa neste link.
Operações com mensagens retornadas¶
Com este plugin conseguimos realizar várias operações com mensagens que foram obtidas após o método de busca.
# Pesquise todos os e-mails onde:
# O assunto é "Importante!"
# Foi enviado pelo endereço de e -mail: some_sender@gmail.com
# Foi enviado após a data de 01/04/2022
mensagens = gmail.search_messages(criteria="subject:Importante! from:some_sender@gmail.com after:01/04/2022")
# Para cada e -mail encontrado:
# Marcar como Lido
# Baixe arquivos em anexos
# Responder com o texto: "Recebido!"
for msg in mensagens:
gmail.mark_as_read(msg)
gmail.download_attachments(msg, '/minha_pasta')
gmail.reply(msg, "Recebido!")
Como mencionado anteriormente, os e-mails podem ser filtrados usando diferentes combinações, separando os operadores e seus respectivos valores por um espaço em branco.
Com as mensagens retornadas, conseguimos realizar várias operações para cada mensagem específica, como baixar anexos, responder, etc.
Gerenciando Marcadores¶
Na API do Gmail, temos o conceito de marcadores que podem ser atribuídos às mensagens. Usando marcadores, podemos alterar o status de um email, das pastas onde ele será exibido e muito mais.
Com este plugin, também é possível gerenciar esses marcadores, podendo criar novos, adiciona-los a uma mensagem e também removê-los.
from botcity.plugins.gmail import BotGmailPlugin, GmailDefaultLabels
# Instancie o plugin
gmail = BotGmailPlugin(credenciais, "<sua_conta_gmail>")
# Crie uma novo marcador por e-mail
gmail.create_new_label("Meu marcador personalizado")
# Pesquise todos os e-mails com o assunto: Mensagem de Teste
mensagens = gmail.search_messages(criteria="subject:Mensagem de Teste")
for msg in mensagens:
# Retorna todos os marcadores que a mensagem contém
print(msg.labels)
# Adiciona à mensagem um dos marcadores padrão do Gmail e também um marcador personalizado, criado pelo usuário.
gmail.add_labels_to_message(msg, default_labels=[GmailDefaultLabels.STARRED], customized_labels=['Meu Marcador Personalizado'])
Conforme demonstrado no exemplo acima, é possível adicionar marcadores padrão do Gmail à mensagem, como estrela ou importante, e também adicionar marcadores criados pelo usuário.
Os marcadores padrão do Gmail que podem ser usados são definidos como um Enum na classe GmailDefaultLabels, para selecionar um valor use GmailDefaultLabels.LABEL_NAME.
Os marcadores personalizados devem ter um nome unico, e quando utilizados, devem ser passados na operação o nome exato de cada marcador desejado.
Infomação
Para saber mais detalhes sobre marcadores e quais são suas diferenças, acesse este link.
Usando marcadores como filtros¶
Além de nossa string de critérios, também podemos usar marcadores de e-mail como um filtro para as mensagens que queremos retornar.
from botcity.plugins.gmail import BotGmailPlugin, GmailDefaultLabels # Uso: GmailDefaultLabels.<LABEL_NAME>
# Instantiate the plugin
gmail = BotGmailPlugin(credenciais, "<sua_conta_gmail>")
# Retornando mensagens que têm o marcador "lixo", apenas mensagens que estão no lixo serão consideradas
msgs_na_lixeira = gmail.search_messages(default_labels=[GmailDefaultLabels.TRASH])
# Pesquisando usando critérios, marcadores padrão e marcadores personalizadas como filtros
msgs = gmail.search_messages(criteria="before:04/04/2022", default_labels=[GmailDefaultLabels.STARRED, GmailDefaultLabels.UNREAD], customized_labels=['Meu Marcador Personalizado', 'Meu Marcador Personalizado 2'])
Dessa forma, podemos combinar e criar filtros da maneira que quisermos. Somente mensagens que têm essas características e são definidas com os marcadores informados serão retornadas.
Também temos a opção de não usar marcadores nos filtros. Nesse caso, serão consideradas por padrão as mensagens que estiverem na caixa de entrada.
Enviando mensagens¶
Além de acessar e-mails recebidos, também podemos responder, encaminhar e enviar novas mensagens.
# Instancie o plugin
gmail = BotGmailPlugin(credenciais, "<sua_conta_gmail>")
# Definindo os atributos que comporão a mensagem
para = ["<ENDEREÇO_DESTINATARIO_1>", "<ENDEREÇO_DESTINATARIO_2>"]
cc = ["<OUTRO_ENDEREÇO>"]
assunto = "Olá Mundo!"
corpo_email = "Olá! Esta é uma mensagem de teste!"
arquivo = ["meu_arquivo.txt"]
# Enviando a mensagem de e-mail
gmail.send_message(assunto, corpo_email, para, cc, attachments=arquivo, use_html=False)
Responder ou encaminhar mensagens¶
# Procurando todos os e-mails que foram estrelados
mensagens = gmail.search_messages(default_labels=[GmailDefaultLabels.STARRED])
# Para cada e-mail, resposta ou encaminhe, dependendo do assunto
for msg in mensagens:
if msg.subject == "Responda esta msg!":
gmail.reply_to_all(msg, "Ei!")
else:
gmail.forward(msg, to=["<ENDEREÇO_DESTINATARIO_1>", "<ENDEREÇO_DESTINATARIO_2>"])