Office 365

Actions to read, navigate, download attachments and send emails using the Office 365 API.

To use these actions you must have Azure app credentials: Tenant ID, Client ID, Client Secret and User ID.

To follow a step-by-step guide to create the app: Azure App Creation Tutorial

Note: the folder_name default is set to Caixa de Entrada in the client constructor.

Return values (state variables) - Actions expose returned values as state variables that can be read by the integrator. - To read a returned value, assign a local variable from the state variable using the $ prefix. The name must match exactly the key returned by the action.

Generic example:

# call the action
office365.create_office365_client("TENANT", "CLIENT", "SECRET", "USER")

# read the client and email count
email_client = $email_client
emails_count = $emails_count

Actions

The actions below are available and documented with parameters, return values and usage examples.

office365.create_office365_client

Create a new connection to Office 365 API and load the initial list of emails.

Parameters:

tenant_id — Tenant ID for the Azure app.
client_id — Client ID for the Azure app.
client_secret — Client Secret for the app.
user_id — User ID (mailbox) to connect.
pagination_limit (optional) — number of emails per page (default: 50).
folder_name (optional) — initial folder name (default: Caixa de Entrada).

Return:

email_client — connection object to be used in subsequent actions.
emails_count — total number of emails in the default folder after load.
current_folder — current folder name (string). Default return value is inbox.

Usage example:

office365.create_office365_client("TENANT", "CLIENT", "SECRET", "USER")
email_client = $email_client
emails_count = $emails_count
current_folder = $current_folder

office365.find_attachments

Return attachments from the current email or filter by partial name.

Parameters:

email_client — connection object.
attach_name (optional) — name or partial name to filter attachments.

Return:

attachments — list with metadata of found attachments (each item contains name, contentBytes, etc.).
attachments_count — number of attachments found.

Usage example:

office365.find_attachments($email_client, "report")
attachments = $attachments
attachments_count = $attachments_count

Notes: - attachments contains base64 content in contentBytes when you need to save the files locally.

office365.get_current_email

Return details for the email at the client's current position (active email).

Parameters:

email_client — object returned by office365.create_office365_client.

Return:

id — email identifier in Office 365 API.
from — sender name.
from_address — sender email address.
subject — message subject.
date — received date/time.
has_attachments — boolean indicating if attachments exist.
html_body — message body as HTML.
check_read — boolean indicating if message was read.

Usage example:

office365.get_current_email($email_client)
email_id = $id
from_name = $from
subject = $subject

office365.list_folders

Return the list of folders available in the connected mailbox.

Parameters:

email_client — connection object.

Return:

folders — list of folder names available.

Usage example:

office365.list_folders($email_client)
folders = $folders

office365.move_to

Move the current email to another existing folder.

Parameters:

email_client — connection object.
to_folder — destination folder name.

Return:

This action does not return state variables.

Usage example:

office365.move_to($email_client, "Archive")
# no variables to read

office365.next_email

Move the current position to the next (more recent) email and return its details.

Parameters:

email_client — connection object.

Return:

same fields as get_current_email (id, from, from_address, subject, date, has_attachments, html_body, check_read).

Usage example:

office365.next_email($email_client)
next_id = $id

office365.previous_email

Move the current position to the previous (older) email and return its details.

Parameters:

email_client — connection object.

Return:

same fields as get_current_email.

Usage example:

office365.previous_email($email_client)
prev_subject = $subject

office365.save_attachment

Save attachments from the current email to a local folder. If a file with the same name exists, the file will be saved with a -1, -2 suffix to avoid overwriting.

Parameters:

email_client — connection object.
file_path — local folder where files will be saved.
attach_name (optional) — partial name to filter attachments.
mime_type (optional) — (not currently used, reserved).
only_attachments (optional) — (not currently used, reserved).

Return:

saved_files — list with full paths for the saved files.

Usage example:

office365.save_attachment($email_client, "C:/temp", attach_name="invoice")
saved_files = $saved_files

Exceptions: - FileNotFoundException — raised when no attachment is found to save.

office365.select_folder

Select the specified folder and reload messages for that folder.

Parameters:

email_client — connection object.
folder_name — folder name to select.

Return:

current_folder — selected folder name.
emails_count — number of emails present in the selected folder.

Usage example:

office365.select_folder($email_client, "Drafts")
current_folder = $current_folder
emails_count = $emails_count

office365.send_email

Send an email using the connected account.

Parameters:

email_client — connection object.
to — list or string with recipients for TO.
subject — message subject.
text (optional) — plain text body.
html (optional) — HTML body.
attachments (optional) — list of file paths to attach.
to_cc (optional) — list of CC recipients.
to_bcc (optional) — list of BCC recipients.

Return:

email_sent — boolean indicating whether the send succeeded.
status_code — status code returned by the API.
message_status — message with details about the sending result.

Usage example:

office365.send_email($email_client, ["[email protected]"], "Subject", text="hello")
email_sent = $email_sent
status_code = $status_code
message_status = $message_status