Google - Gmail¶
Interactúa y realiza diversas operaciones a través de una cuenta de Google. Envía, recupera y responde a mensajes de correo electrónico fácilmente a través del complemento BotCity para Gmail.
Instalación¶
Importando el complemento¶
Después de instalar este paquete y obtener el archivo de credenciales de Google, el siguiente paso es importar el paquete en tu código y comenzar a usar las funciones.
Configuración del correo electrónico¶
Primero, configuremos la cuenta de Gmail y las credenciales que utilizaremos en el código.
Info
Tu cuenta de Gmail debe ser la misma que se utilizó para generar las credenciales.
Buscando algunos mensajes¶
Con la cuenta configurada correctamente, filtremos y busquemos algunos correos electrónicos.
# Search for all emails with subject: Hello World
messages = gmail.search_messages(criteria="subject:Hello World")
# For each email found: prints the subject, sender address and text content of the email
for msg in messages:
print("\n----------------------------")
print("Subject => " + msg.subject)
print("From => " + msg.from_)
print("Msg => " + msg.text)
En este ejemplo, solo se utilizó el atributo subject como filtro. Sin embargo, la API de Gmail ofrece diferentes posibilidades, utilizando otras combinaciones y operadores. Obtén más detalles sobre los operadores de búsqueda en este enlace.
Operaciones con los mensajes obtenidos¶
Con este complemento, pudimos realizar varias operaciones con los mensajes obtenidos después del método de búsqueda.
# Search for all emails where:
# The subject is "Important!"
# It was sent by the email address: some_sender@gmail.com
# It was sent after the date of 01/04/2022
messages = gmail.search_messages(criteria="subject:Important! from:some_sender@gmail.com after:01/04/2022")
# For each email found:
# Mark as read
# Download files in attachments
# Reply with the text: "Received!"
for msg in messages:
gmail.mark_as_read(msg)
gmail.download_attachments(msg, '/my_folder')
gmail.reply(msg, "Received!")
Como se mencionó anteriormente, los correos electrónicos se pueden filtrar utilizando diferentes combinaciones, separando los operadores y sus respectivos valores con un espacio en blanco.
Con los mensajes obtenidos, pudimos realizar varias operaciones para cada mensaje específico, como descargar archivos adjuntos, responder, etc.
Administrando etiquetas¶
En la API de Gmail, tenemos el concepto de etiquetas que se pueden asignar a los mensajes. Usando etiquetas, podemos cambiar el estado de un correo electrónico, las carpetas donde se mostrará y mucho más.
Con este complemento, también es posible administrar estas etiquetas, pudiendo crear nuevas, agregar etiquetas a un mensaje y también eliminarlas.
from botcity.plugins.gmail import BotGmailPlugin, GmailDefaultLabels
# Instantiate the plugin
gmail = BotGmailPlugin(credentials, "<your_gmail_account>")
# Create a new label on email
gmail.create_new_label("My Custom Label")
# Search for all emails with subject: Test Message
messages = gmail.search_messages(criteria="subject:Test Message")
for msg in messages:
# Returns all labels that the message contains
print(msg.labels)
# Adds to the message one of the standard gmail labels and also a custom label, created by the user.
gmail.add_labels_to_message(msg, default_labels=[GmailDefaultLabels.STARRED], customized_labels=['My Custom Label'])
Como se muestra en el ejemplo anterior, es posible agregar etiquetas estándar de Gmail al mensaje, como STARRED o IMPORTANT, y también agregar etiquetas creadas por el usuario.
Las etiquetas predeterminadas de Gmail que se pueden utilizar se definen como un Enum en la clase GmailDefaultLabels, para seleccionar un valor, utiliza GmailDefaultLabels.LABEL_NAME.
Las etiquetas personalizadas deben tener un nombre único y, al usarlas, se debe pasar el nombre exacto de cada etiqueta deseada en la operación.
Info
Para obtener más detalles sobre las etiquetas y cuáles son sus diferencias, visita este enlace.
Usando etiquetas como filtros¶
Además de nuestra cadena de criterios, también podemos usar etiquetas de correo electrónico como filtro para los mensajes que queremos devolver.
from botcity.plugins.gmail import BotGmailPlugin, GmailDefaultLabels # Usage: GmailDefaultLabels.<LABEL_NAME>
# Instantiate the plugin
gmail = BotGmailPlugin(credentials, "<your_gmail_account>")
# Returning messages that have the "TRASH" label, only messages that are in the trash will be considered
msgs_on_trash = gmail.search_messages(default_labels=[GmailDefaultLabels.TRASH])
# Searching using criteria, default labels and custom labels as filters
msgs = gmail.search_messages(criteria="before:04/04/2022", default_labels=[GmailDefaultLabels.STARRED, GmailDefaultLabels.UNREAD], customized_labels=['My Custom Label 1', 'My Custom Label 2'])
De esta manera, podemos combinar y crear filtros de la forma que deseemos. Solo se devolverán los mensajes que tengan estas características y estén marcados con las etiquetas informadas.
También tenemos la opción de no usar ninguna etiqueta en los filtros. En este caso, los mensajes que estén en la BANDEJA DE ENTRADA se considerarán de forma predeterminada.
Enviando mensajes¶
Además de acceder a los correos electrónicos recibidos, también podemos responder, reenviar y enviar nuevos mensajes.
# Instantiate the plugin
gmail = BotGmailPlugin(credentials, "<your_gmail_account>")
# Defining the attributes that will compose the message
to = ["<RECEIVER_ADDRESS_1>", "<RECEIVER_ADDRESS_2>"]
cc = ["<ANOTHER_ADDRESS>"]
subject = "Hello World"
body = "Hello! This is a test message!"
files = ["my_file.txt"]
# Sending the email message
gmail.send_message(subject, body, to, cc, attachments=files, use_html=False)
Responder o reenviar mensajes¶
# Searching for all emails that have been starred
messages = gmail.search_messages(default_labels=[GmailDefaultLabels.STARRED])
# For each email, reply or forward depending on the subject
for msg in messages:
if msg.subject == "Reply this msg!":
gmail.reply_to_all(msg, "Hey!")
else:
gmail.forward(msg, to=["<RECEIVER_ADDRESS_1>", "<RECEIVER_ADDRESS_2>"])