Microsoft 365 - Outlook¶

Process your email messages through a Microsoft 365 account. Filter, read, and send new messages easily through the BotCity plugin for Outlook.

Warning

To be able to use this plugin, you need to have a Microsoft 365 account with a properly created and configured project.

After creating a project, you need to complete the authentication process through the Microsoft 365 Credentials plugin.

For more details, see the previous sections:

Installation¶

PythonJava

pip install botcity-ms365-outlook-plugin

Importing the Plugin¶

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

PythonJava

from botcity.plugins.ms365.outlook import MS365OutlookPlugin

Setting the service account¶

As mentioned above, in order to use the Outlook plugin, it is necessary to perform the account authentication process through the Microsoft 365 Credentials plugin.

With the credentials plugin instance obtained, let's use it to instantiate the Outlook plugin.

PythonJava

from botcity.plugins.ms365.credentials import MS365CredentialsPlugin, Scopes
from botcity.plugins.ms365.outlook import MS365OutlookPlugin

# Instantiate the Credentials plugin
service = MS365CredentialsPlugin(
    client_id='<APPLICATION ID>',
    client_secret='<SECRET VALUE>',
)
service.authenticate(scopes=[Scopes.BASIC, Scopes.MAIL_READ_WRITE])

# Instantiate the Outlook Plugin
outlook = MS365OutlookPlugin(service_account=service)

Tip

To use the Outlook service, just add the scope Scopes.MAIL_READ_WRITE referring to the Mail.ReadWrite and Mail.Send permissions of the project.

See more details about scopes and permissions at this link.

Managing email folders¶

We can perform various operations with email folders. You can create, delete, and get existing folders.

PythonJava

outlook = MS365OutlookPlugin(service_account=service)

# Creating a new folder
outlook.create_folder("TestFolder")

# Deleting an existing folder
outlook.delete_folder("MyFolder")

# Getting the reference of a specific folder
folder = outlook.get_folder("MessagesToRead")

# Returning existing folders in email
for folder in outlook.get_folders():
    print(folder.name)

In addition to returning all email folders from the "root" folder, it is also possible to use a parent folder as a reference.

This way, we could return all the subfolders within a more specific context.

PythonJava

outlook = MS365OutlookPlugin(service_account=service)

# Getting the reference of a specific folder
folder = outlook.get_folder("MessagesToRead")

# Returning only the subfolders of the parent folder "MessagesToRead"
for folder in outlook.get_folders(parent_folder=folder):
    print(folder.name)

We can also configure an e-mail folder to be used as a reference in message search operations.

Tip

By default, the inbox folder will be used as a reference for operations.

If you want to use a different folder as a reference, configure it using the set_default_folder method.

PythonJava

outlook = MS365OutlookPlugin(service_account=service)

# Getting the reference of a specific folder
folder = outlook.get_folder("TestFolder")

# Setting the default folder
outlook.set_default_folder(folder=folder)

# It is also possible to configure using the folder name
outlook.set_default_folder(folder="TestFolder")

Fetching email messages¶

We were able to search for email messages using specific filters easily.

Note

The filters are based on Open Data Protocol (OData) and can have different complexities.

See more details on how to create advanced filters in the section Using email attributes and filters.

PythonJava

outlook = MS365OutlookPlugin(service_account=service)

# Creating a new filter through the Query object
query_filter = outlook.new_query_filter()

# Filter using email subject
query_filter.on_attribute("subject").equals("Test Message")

# Searching for all emails with the subject "Test Message"
messages = outlook.search_messages(criteria=query_filter)
for msg in messages:
    print(msg)

Managing email messages¶

The search method returns a list of all found messages. With these message objects returned, we can access some specific properties.

PythonJava

outlook = MS365OutlookPlugin(service_account=service)

# Creating a new filter through the Query object
query_filter = outlook.new_query_filter()

# Filter using the address that sent the message
query_filter.on_attribute("from").equals("user@email.com")

# Fetching emails and getting specific properties
messages = outlook.search_messages(criteria=query_filter)
for msg in messages:
    print(msg.subject)
    print(msg.body_preview)
    print(msg.received)

In addition to accessing specific properties, we can also perform some operations with the obtained messages.

Replying and forwarding messages¶

PythonJava

messages = outlook.search_messages(criteria=query_filter)

# Replying or forwarding each email depending on the subject
for msg in messages:
    if msg.subject == "Reply this message":
        outlook.reply_to_all(msg=msg, text_content="OK!")
    else:
        outlook.forward(msg=msg, to_addrs=["email_1", "email_2"])

Performing operations with messages¶

PythonJava

messages = outlook.search_messages(criteria=query_filter, include_attachments=True)

for msg in messages:
    # Marking the message as "read"
    outlook.mark_as_read(msg)

    # Downloading message attachments
    outlook.download_attachments(msg, download_folder_path="./Downloads")

# Copying a message to another email folder
outlook.copy(msg=messages[0], folder_name="SubFolder")

# Moving a message to another email folder
outlook.move(msg=messages[0], folder_name="MyFolder")

# Deleting a message from the email folder
outlook.delete(msg=messages[0])

Warning

To download files attached to a message, it is necessary to configure the include_attachments=True parameter in the search_messages method.

By default, the API returns messages without the attachment content.

Sending messages¶

In addition to accessing received email messages, we can send new ones.

PythonJava

outlook = MS365OutlookPlugin(service_account=service)

# Defining message attributes
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
outlook.send_message(subject, body, to, cc, attachments=files)

Tip

You can also send messages with HTML formatting. Just include the desired formatting in the message body string.