Microsoft 365 - Outlook¶

Processe suas mensagens de e-mail por meio de uma conta do Microsoft 365. Filtre, leia e envie novas mensagens facilmente através do plugin BotCity para o Outlook.

Aviso

Para poder usar este plugin, você precisa ter uma conta do Microsoft 365 com um projeto criado e configurado corretamente.

Depois de criar um projeto, você precisa concluir o processo de autenticação por meio do plugin Microsoft 365 Credentials.

Para mais detalhes, consulte as seções anteriores:

Instalação¶

PythonJava

pip install botcity-ms365-outlook-plugin

Importando o Plugin¶

Depois de instalar este pacote, a próxima etapa é importar o pacote no seu código e começar a usar as funções.

PythonJava

from botcity.plugins.ms365.outlook import MS365OutlookPlugin

Configurando a conta de serviço¶

Conforme mencionado acima, para usar o plugin do Outlook, é necessário realizar o processo de autenticação da conta por meio do plugin Microsoft 365 Credentials.

Com a instância do plugin de credenciais obtida, vamos usá-la para instanciar o plugin do Outlook.

PythonJava

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

# Instanciando o plugin de Credenciais
service = MS365CredentialsPlugin(
    client_id='<APPLICATION ID>',
    client_secret='<SECRET VALUE>',
)
service.authenticate(scopes=[Scopes.BASIC, Scopes.MAIL_READ_WRITE])

# Instanciando o plugin do Outlook
outlook = MS365OutlookPlugin(service_account=service)

Dica

Para utilizar o serviço do Outlook, basta adicionar o escopo Scopes.MAIL_READ_WRITE referente às permissões Mail.ReadWrite e Mail.Send do projeto.

Veja mais detalhes sobre escopos e permissões nesse link.

Gerenciando pastas do e-mail¶

Podemos realizar diversas operações com as pastas do e-mail. É possível criar, deletar e obter a referência das pastas existentes.

PythonJava

outlook = MS365OutlookPlugin(service_account=service)

# Criando uma nova pasta
outlook.create_folder("TestFolder")

# Excluindo uma pasta existente
outlook.delete_folder("MyFolder")

# Obtendo a referência de uma pasta específica
folder = outlook.get_folder("MessagesToRead")

# Retornando as pastas existentes no email
for folder in outlook.get_folders():
    print(folder.name)

Além de retornar todas as pastas do e-mail a partir da pasta "raiz", também é possível utilizar uma pasta pai como referência.

Dessa forma, conseguimos retornar todas as subpastas dentro de um contexto mais específico.

PythonJava

outlook = MS365OutlookPlugin(service_account=service)

# Obtendo a referência de uma pasta específica
folder = outlook.get_folder("MessagesToRead")

# Retornando somente as subpastas da pasta pai "MessagesToRead"
for folder in outlook.get_folders(parent_folder=folder):
    print(folder.name)

Podemos também configurar uma pasta do e-mail para ser utilizada como referência nas operações de buscar mensagens.

Dica

Por padrão, será utilizada a pasta da caixa de entrada como referência para as operações.

Caso você queira utilizar uma pasta diferente como referência, basta configurar através do método set_default_folder.

PythonJava

outlook = MS365OutlookPlugin(service_account=service)

# Obtendo a referência de uma pasta específica
folder = outlook.get_folder("TestFolder")

# Configurando a pasta padrão
outlook.set_default_folder(folder=folder)

# Também é possível configurar utilizando o nome da pasta
outlook.set_default_folder(folder="TestFolder")

Buscando mensagens de e-mail¶

Conseguimos facilmente procurar por mensagens de e-mail utilizando filtros específicos.

Observação

Os filtros são baseados no Open Data Protocol (OData) e podem ter diferentes complexidades.

Veja mais detalhes sobre como criar filtros avançados na seção Usando atributos e filtros de e-mail.

PythonJava

outlook = MS365OutlookPlugin(service_account=service)

# Criando um novo filtro através do objeto Query
query_filter = outlook.new_query_filter()

# Filtro utilizando o assunto do email
query_filter.on_attribute("subject").equals("Test Message")

# Buscando todos os emails que tenham como assunto "Test Message"
messages = outlook.search_messages(criteria=query_filter)
for msg in messages:
    print(msg)

Gerenciando as mensagens de e-mail¶

O método search retorna uma lista com todas as mensagens que foram encontradas. Com esses objetos de mensagem retornados, podemos acessar algumas propriedades específicas.

PythonJava

outlook = MS365OutlookPlugin(service_account=service)

# Criando um novo filtro através do objeto Query
query_filter = outlook.new_query_filter()

# Filtro utilizando o endereço que enviou a mensagem
query_filter.on_attribute("from").equals("user@email.com")

# Buscando os emails e exibindo propriedades específicas
messages = outlook.search_messages(criteria=query_filter)
for msg in messages:
    print(msg.subject)
    print(msg.body_preview)
    print(msg.received)

Além de acessar propriedades específicas, também podemos realizar algumas operações com as mensagens obtidas.

Respondendo e encaminhando mensagens¶

PythonJava

messages = outlook.search_messages(criteria=query_filter)

# Respondendo ou encaminhando cada e-mail, dependendo do assunto
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"])

Realizando operações com as mensagens¶

PythonJava

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

for msg in messages:
    # Marcando a mensagem como "lida"
    outlook.mark_as_read(msg)

    # Baixando os anexos da mensagem, caso existir
    outlook.download_attachments(msg, download_folder_path="./Downloads")

# Copiando uma mensagem para uma outra pasta do email
outlook.copy(msg=messages[0], folder_name="SubFolder")

# Movendo uma mensagem para uma outra pasta do email
outlook.move(msg=messages[0], folder_name="MyFolder")

# Excluindo uma mensagem da pasta do email
outlook.delete(msg=messages[0])

Aviso

Para conseguir baixar os arquivos em anexo de uma mensagem, é necessário configurar o parâmetro include_attachments=True no método search_messages.

Por padrão, a API retorna as mensagens sem o contéudo dos anexos.

Enviando mensagens¶

Além de acessar as mensagens de e-mail recebidas, também podemos enviar novas mensagens.

PythonJava

outlook = MS365OutlookPlugin(service_account=service)

# Definindo os atributos da mensagem
to = ["<RECEIVER_ADDRESS_1>", "<RECEIVER_ADDRESS_2>"]
cc = ["<ANOTHER_ADDRESS>"]
subject = "Hello World"
body = "Hello! This is a test message!"
files = ["my_file.txt"]

# Enviando a mensagem de e-mail
outlook.send_message(subject, body, to, cc, attachments=files)

Dica

Você também consegue enviar mensagens com a formatação do HTML. Basta incluir a formatação desejada na string do corpo da mensagem.