After you installed this package and get the Google credentials file, the next step is to import the package into your code and start using the functions.
from botcity.plugins.gmail import BotGmailPlugin
As a demonstration of the library, let's see some examples and features.
Setting up the email
First, let's configure the gmail account and the credentials that we will use in the code.
# Set the path of the credentials json file credentials = './resources/credentials.json' # Instantiate the plugin gmail = BotGmailPlugin(credentials, "<your_gmail_account>")
Your gmail account must be the same as the one used to generate the credentials.
Searching for some messages
With the account properly configured, let's filter and search for some emails.
# 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)
Operations with returned messages
With this plugin we were able to perform several operations with messages that were obtained after the search method.
# Search for all emails where: # The subject is "Important!" # It was sent by the email address: firstname.lastname@example.org # It was sent after the date of 01/04/2022 messages = gmail.search_messages(criteria="subject:Important! from:email@example.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!")
With the returned messages, we were able to perform various operations for each specific message, such as downloading attachments, replying, etc.
In the Gmail API we have the concept of labels that can be assigned to messages. Using labels, we are able to change the status of an email, the folders where it will be displayed and much more.
With this plugin it is also possible to manage these labels, being able to create new ones, add labels to a message and also remove them.
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'])
The default Gmail labels that can be used are defined as an Enum in the GmailDefaultLabels class, to select a value use GmailDefaultLabels.LABEL_NAME.
The personalized labels must have a unique name, and when used, the exact name of each desired label must be passed in the operation.
To see more details about labels and what are their differences, visit this link.
Using labels as filters
In addition to our criteria string, we can also use email labels as a filter for the messages we want to return
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'])
We also have the option of not using any labels in the filters. In this case, the messages that are in the INBOX will be considered by default.
In addition to accessing received emails, we are also able to reply, forward and send new messages.
# 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)
Replying or forwarding messages
# 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>"])
Check our examples and experiment with the API. Let us know where it can be improved.
Have fun automating!