Skip to content

Getting Started

After you installed this package, the next step is to import the package into your code and start using the functions.

from botcity.plugins.email import BotEmailPlugin

As a demonstration of the library, let's build a simple example together that will do something cool.

Warning

In some cases, in order to be able to use the email functionalities through the IMAP and SMTP protocols, it is necessary to activate the permission to use both protocols in the account settings. In addition, it may also be necessary to enable the option for less secure applications. (details here)

Warning

We recommend disabling two-factor authentication for email accounts to avoid any type of bot blocking. If you are using an account with two-factor authentication and it is not possible to disable it, see the App Passwords section.

Setting up email account

First, let's configure our email account and login with the credentials.

# Instantiate the plugin
email = BotEmailPlugin()

# Configure IMAP with the gmail server
email.configure_imap("imap.gmail.com", 993)

# Configure SMTP with the gmail server
email.configure_smtp("imap.gmail.com", 587)

# Login with a valid email account
email.login("<USER_EMAIL>", "<USER_PASSWORD>")

Info

You can use different mail servers, the information about some servers can be seen on this page.

Alternative setup

You have the option to configure the servers that will be used the way you want. However, in some cases you can simply use the default settings of a known server and connect your account quickly.

The configuration above could also look like this: 

from botcity.plugins.email import BotEmailPlugin, MailServers

# Configure and log in on the same method, using the default Gmail server settings
email = BotEmailPlugin.config_email(MailServers.GMAIL, "<USER_EMAIL>","<USER_PASSWORD>")
...

Fetching some email messages

With the configured plugin instance, we will retrieve some email messages.

Note

Please, avoid using words that contain accents or special characters when using the methods to filter and search for messages. This is a issue from the email servers, causing an exception when trying to search for emails using special characters in the filter.

# Search for all emails with subject: Test Message
messages = email.search('SUBJECT "Test Message"')

# For each email found: prints the date, sender address and text content of the email
for msg in messages:
    print("\n---------------------------")
    print("Date => " + msg.date_str)
    print("From => " + msg.from_)
    print("Msg => " + msg.text)

Info

In this example, the SUBJECT attribute was used as a filter, you can have an idea of the attributes that can be used in this link.

Another way for fetching some email messages

In the search method used above it is necessary to pass a string containing the filter that will be used. However, in some cases it can be confusing and it is difficult to build the filter correctly.

Therefore, through the filter_by method it is possible to select the attribute that will be used in the filter and pass the value of this attribute. Making it much easier to build filters when retrieving messages. 

from botcity.plugins.email import MailFilters

# Search for all emails with subject: Test Message
messages = email.filter_by(MailFilters.SUBJECT, "Test Message")
...

Sending a new message from scratch

After retrieving some emails, we will send a new message.

# Defining the attributes that will compose the message 
to = ["<RECEIVER_ADDRESS_1>", "<RECEIVER_ADDRESS_2>"]
subject = "Hello World"
body = "<h1>Hello!</h1> This is a test message!"
files = ["my_file.txt"]

# Sending the email message
email.send_message(subject, body, to, attachments=files, use_html=True)

# Close the conection with the IMAP and SMTP servers
email.disconnect()

Complete code

Let's take a look into the complete code:

# Import the plugin
from botcity.plugins.email import BotEmailPlugin

# Instantiate the plugin
email = BotEmailPlugin()

# Configure IMAP with the gmail server
email.configure_imap("imap.gmail.com", 993)

# Configure SMTP with the gmail server
email.configure_smtp("imap.gmail.com", 587)

# Login with a valid email account
email.login("<USER_EMAIL>", "<USER_PASSWORD>")

# Search for all emails with subject: Test Message
messages = email.search('SUBJECT "Test Message"')

# For each email found: prints the date, sender address and text content of the email
for msg in messages:
    print("\n---------------------------")
    print("Date => " + msg.date_str)
    print("From => " + msg.from_)
    print("Msg => " + msg.text)

# Defining the attributes that will compose the message 
to = ["<RECEIVER_ADDRESS_1>", "<RECEIVER_ADDRESS_2>"]
subject = "Hello World"
body = "<h1>Hello!</h1> This is a test message!"
files = ["my_file.txt"]

# Sending the email message
email.send_message(subject, body, to, attachments=files, use_html=True)

# Close the conection with the IMAP and SMTP servers
email.disconnect()

Next Steps

Check our examples and experiment with the API. Let us know where it can be improved.

Have fun automating!

Back to top