Microsoft Outlook

Procedures and concepts for the Microsoft Outlook integration.

The following documentation is for Microsoft Outlook v2.2.3 (BDK).

Overview

Microsoft Outlook provides enterprise email management with calendar, contacts, and task integration capabilities. This integration enables automated email processing, calendar management, and communication workflows. Streamline business communication and enhance productivity through automated email operations.

Prerequisites

1. Required Books

The following Book(s) need to be added to your agent so it can learn and understand the automation procedures defined within them:

• Microsoft Outlook

How to Add the Book(s)

1. Go to Books → All Books.

2. Search for the name of the book and click on it.

3. Click on Install or Add Connection to add the book to your agent.

4. If adding a connection, you'll be prompted for connectivity details.

Connectivity

This section outlines the available methods for connecting to the Book, along with the required configuration details for each.

This books supports the connectivity methods described in this section.In here you will find information about what information is required in order to employ each method.

Connect using Client ID, Client Secret and Tenant ID

Connect to the Microsoft Graph API using the provided client credentials.

Label	Description	Type
Client ID	The client ID of the application registered in Azure AD.	text
Client Secret	The client secret of the application registered in Azure AD.	text
Tenant ID	The tenant ID of the Azure AD directory.	text

Connect using Client ID, Certificate and Tenant ID

Connect to the Microsoft Graph API using certificate credentials.

Label	Description	Type
Client ID	The client ID of the application registered in Azure AD.	text
Certificate	PEM-encoded X.509 certificate string containing both the certificate and private key.	sensitive
Tenant ID	The tenant ID of the Azure AD directory.	text

Connect using Client ID, Certificate, Private Key and Tenant ID

Connect to the Microsoft Graph API using certificate and private key.

Label	Description	Type
Client ID	The client ID of the application registered in Azure AD.	text
Certificate	PEM-encoded certificate string.	sensitive
Private Key	PEM-encoded private key string.	sensitive
Tenant ID	The tenant ID of the Azure AD directory.	text

Procedures

to delete some emails

Delete specific emails from an Outlook account.

It requires the following permissions on the scopes: Mail.ReadWrite, Mail.ReadWrite.Shared

Input Concepts

Concept	Description	Type	Required	Default Value
emails	The emails to be deleted	outlook email	Yes	(no default)

Examples

Delete the specified emails

...
use the above as the emails
delete the emails

to download an attachment

Download an attachment from an event or email.

It requires the following permissions on the application: Calendars.ReadBasic, Calendars.Read, Calendars.ReadWrite

Input Concepts

Concept	Description	Type	Required	Default Value
attachment	The attachment that will be downloaded	outlook attachment	Yes	(no default)

Output Concepts

Concept	Description	Type
answer	The attachment as a file object	file

Examples

Download the attachment for the specified event

get users from office365 whose mail is "[email protected]"
get the first user
get the above's events from outlook
get the first event
get the above's attachments
get the first attachment
use the above as the attachment
download the attachment

to forward an email to a recipient

Forward an email to a specified recipient or group of recipients.

It requires the following permissions on the scopes: Mail.ReadWrite, Mail.ReadWrite.Shared, Mail.Send

Input Concepts

Concept	Description	Type	Required	Default Value
email	The email to be forwarded	outlook email	Yes	(no default)
recipient	The recipient or recipients of the email	list of text or text	Yes	(no default)
subject	The subject of the forwarded email	text	No	(no default)
cc recipients	The cc recipients of the forwarded email	list of text or text	No	(no default)
bcc recipients	The bcc recipients of the forwarded email	list of text or text	No	(no default)
attachments	The attachments to be sent with the forwarded email	file	No	(no default)

Examples

Forward the specified email to the specified recipients

...
use the first email as the email
the recipients are "[email protected]", "[email protected]"
forward the email to the recipients

Forward the specified email to the specified recipients with custom subject

...
use the first email as the email
the recipients are "[email protected]", "[email protected]"
forward the email to the recipients with
... the subject is "FW by me: Meeting Reminder"

Forward the specified email to the specified recipients with custom cc recipients

...
use the first email as the email
the recipients are "[email protected]", "[email protected]"
the cc recipients are "[email protected]", "[email protected]"
forward the email to the recipients with
... the cc recipients is the cc recipients

Forward the specified email to the specified recipients with custom bcc recipients

...
use the first email as the email
the recipients are "[email protected]", "[email protected]"
the bcc recipients are "[email protected]", "[email protected]"
forward the email to the recipients with
... the bcc recipients is the bcc recipients

Forward the specified email to the specified recipients with attachments

...
use the first email as the email
...
use the above as the file
...
use the above as the other file
the attachments are the file, the other file
the recipients are "[email protected]", "[email protected]"
forward the email to the recipients with
... the attachments is the attachments

to get a (group's events) from outlook

FILTER - CAPABLE

Get all the events from a group's calendar.

It requires the following permissions on the application: Calendars.Read, Calendars.ReadWrite

Input Concepts

Concept	Description	Type	Required	Default Value
group	The user's or group's calendar from where the events will be retrieved from	office group	Yes	(no default)
start date time	The start date and time of the events to be retrieved	text	Yes	(no default)
end date time	The end date and time of the events to be retrieved	text	Yes	(no default)

Output Concepts

Concept	Description	Type
group's events	All the events for the group	outlook event

Examples

Retrieve all events for the specified group

get groups from office365 whose mail is "[email protected]"
get the first group
get the above's events from outlook
... the start date time is "2022-07-14T12:30:00Z"
... the end date time is "2022-07-15T12:30:00Z"

Retrieve all events for the specified group whose subject matches the specified one

get groups from office365 whose mail is "[email protected]"
get the first group
get the above's events from outlook whose subject is "Birthday Party"
... the start date time is "2022-07-14T12:30:00Z"
... the end date time is "2022-07-15T12:30:00Z"

to get a (user's event's attachments)

Get all the attachments from a user's event.

It requires the following permissions on the application: Calendars.ReadBasic, Calendars.Read, Calendars.ReadWrite

Input Concepts

Concept	Description	Type	Required	Default Value
user	The user's calendar from where the event attachments will be retrieved from	office user	Yes	(no default)
event	The event from where the attachments will be retrieved from	outlook event	Yes	(no default)

Output Concepts

Concept	Description	Type
user's event's attachments	All the attachments for the event	outlook attachment

Examples

Retrieve all attachments for the specified event

get users from office365 whose mail is "[email protected]"
get the first user
get the above's events from outlook
get the first event
get the above's attachments

to get a (user's events) from outlook

FILTER - CAPABLE

Get all the events from a user's calendar.

It requires the following permissions on the application: Calendars.ReadBasic, Calendars.Read, Calendars.ReadWrite

Input Concepts

Concept	Description	Type	Required	Default Value
user	The user's calendar from where the events will be retrieved from	office user	Yes	(no default)

Output Concepts

Concept	Description	Type
user's events	All the events for the user	outlook event

Examples

Retrieve all events for the specified user

get users from office365 whose mail is "[email protected]"
use the first user as john
get john's events from outlook

Retrieve all events for the specified user whose subject matches the specified one

get users from office365 whose mail is "[email protected]"
use the first user as john
get john's events from outlook whose subject is "Birthday Party"

Retrieve all events whose start date is after Jul 7, 2022 12:30 UTC

get users from office365 whose mail is "[email protected]"
use the first user as john
get john's events from outlook whose "start/dateTime" is greater than "2022-07-14T12:30:00Z"

to get an email folder's subfolders

FILTER - CAPABLE

Get all the subfolders from an email folder.

It requires the following permissions on the scopes: Mail.Read, Mail.ReadWrite, Mail.ReadBasic, Mail.ReadBasic.All, Mail.ReadWrite.Shared

Input Concepts

Concept	Description	Type	Required	Default Value
email folder	The email folder from where the child folders will be retrieved	outlook email folder	Yes	(no default)

Output Concepts

Concept	Description	Type
answer	All the child email folders for the email folder	outlook email folder

Examples

Retrieve all child folders for the specified email folder

...
use the above as the email folder
get the email folder's subfolders

Retrieve all child folders for the specified email folder that match provided name

...
use the above as the email folder
get the email folder's subfolders whose "displayName" is "My Subfolder"

to get some (email folder's emails)

FILTER - CAPABLE

Get emails from an Outlook folder based on specified filters.

It requires the following permissions on the scopes: Mail.Read, Mail.ReadWrite, Mail.ReadBasic, Mail.ReadBasic.All, Mail.ReadWrite.Shared

Input Concepts

Concept	Description	Type	Required	Default Value
email folder	The email folder from where the emails will be retrieved	outlook email folder	Yes	(no default)
limit	The maximum number of emails to retrieve	number	No	(no default)

Output Concepts

Concept	Description	Type
email folder's emails	All the emails for the email folder	outlook email

Examples

Retrieve all emails for the specified email folder

...
use the above as the email folder
get some email folder's emails

Retrieve all emails for the specified email folder whose subject matches the specified one

...
use the above as the email folder
get some email folder's emails whose subject is "Email with attachment"

Retrieve all emails for the specified email folder whose received date is after Feb 25, 2024 12:30 UTC

...
use the above as the email folder
the date is "2024-02-25T12:30:00Z"
get the date as a datetime
use the above as the target
get some email folder's emails whose "receivedDateTime" is greater than the target

Retrieve all emails for the specified email folder whose sender matches the specified one

...
use the above as the email folder
get some email folder's emails whose "from/emailAddress/address" is "[email protected]"

Retrieve all emails for the specified email folder whose read status matches the specified one

...
use the above as the email folder
get some email folder's emails whose "isRead" is True

to get the (attachments) from an email

Get the attachments from an email.

It requires the following permissions on the scopes: Mail.Read, Mail.ReadWrite, Mail.ReadBasic, Mail.ReadBasic.All, Mail.ReadWrite.Shared

Input Concepts

Concept	Description	Type	Required	Default Value
email	The email from where the attachments will be retrieved	outlook email	Yes	(no default)

Output Concepts

Concept	Description	Type
attachments	All the attachments for the email	outlook attachment

Examples

Retrieve all attachments for the specified email

...
use the above as the email
get the attachments from the email

to mark some emails

Mark specified emails as read or unread.

It requires the following permissions on the scopes: Mail.ReadWrite, Mail.ReadWrite.Shared

Input Concepts

Concept	Description	Type	Required	Default Value
emails	The emails to be marked	outlook email	Yes	(no default)
read	The status to mark the emails as. True for read, False for unread.	boolean	No	True

Examples

Mark the specified emails as read

...
use the above as the emails
mark the emails

Mark the specified emails as unread

...
use the above as the emails
mark the emails with
... the read is "False"

to move an email to a target folder

Move emails to a target folder.

It requires the following permissions on the scopes: Mail.ReadWrite, Mail.ReadWrite.Shared

Input Concepts

Concept	Description	Type	Required	Default Value
email	The email or emails that will be moved	list of outlook email or outlook email	Yes	(no default)
target folder	The folder where the emails will be moved	outlook email folder	Yes	(no default)

Examples

Move the specified emails to the target folder

...
use the above as the emails
get some email folders from outlook
use the first email folder as the target folder
move the emails to the target folder

to reply an email

Reply to an email through Outlook with the specified details and attachments.

It requires the following permissions on the scopes: Mail.ReadWrite, Mail.ReadWrite.Shared, Mail.Send

Input Concepts

Concept	Description	Type	Required	Default Value
email	The email to be replied	outlook email	Yes	(no default)
message body	The body of the reply	text	Yes	(no default)
subject	The subject of the reply	text	No	(no default)
recipients	The recipients of the reply	list of text or text	No	(no default)
cc recipients	The cc recipients of the reply	list of text or text	No	(no default)
bcc recipients	The bcc recipients of the reply	list of text or text	No	(no default)
attachments	The attachments to be sent with the reply	file	No	(no default)

Examples

Reply to the specified email

...
use the first email as the email
reply the email with
... the message body is "Thank you for the information"

Reply to the specified email with custom subject

...
use the first email as the email
reply the email with
... the subject is "Re by me: Meeting Reminder"
... the message body is "Thank you for the information"

Reply to the specified email with custom cc recipients

...
use the first email as the email
the cc recipients are "[email protected]", "[email protected]"
reply the email with
... the cc recipients is the cc recipients

Reply to the specified email with custom bcc recipients

...
use the first email as the email
the bcc recipients are "[email protected]", "[email protected]"
reply the email with
... the bcc recipients is the bcc recipients

Reply to the specified email with attachments

...
use the first email as the email
...
use the above as the file
...
use the above as the other file
the attachments are the file, the other file
reply the email with
... the message body is "Thank you for the information"
... the attachments is the attachments

to retrieve some (email folders) from outlook

FILTER - CAPABLE

Get all the email folders from the authenticated user's mailbox.

It requires the following permissions on the scopes: Mail.Read, Mail.ReadWrite, Mail.ReadBasic, Mail.ReadBasic.All, Mail.ReadWrite.Shared

Output Concepts

Concept	Description	Type
email folders	All the email folders for the authenticated user	outlook email folder

Examples

Retrieve all email folders for the authenticated user

retrieve some email folders from outlook

Retrieve all email folders for the authenticated user that match provided name

retrieve some email folders from outlook whose "displayName" is "Inbox"

to retrieve some (user's email folders)

FILTER - CAPABLE

Get all the email folders from a user's mailbox.

It requires the following permissions on the application: Mail.Read, Mail.ReadWrite, Mail.ReadBasic, Mail.ReadBasic.All, Mail.ReadWrite.Shared

Input Concepts

Concept	Description	Type	Required	Default Value
user	The user whose email folders will be retrieved	office user	Yes	(no default)

Output Concepts

Concept	Description	Type
user's email folders	All the email folders for the user	outlook email folder

Examples

Retrieve all email folders for the specified user

get users from office365 whose mail is "[email protected]"
use the first user as the user
retrieve the user's email folders

Retrieve all email folders for the specified user that match provided name

get users from office365 whose mail is "[email protected]"
use the first user as the user
retrieve the user's email folders whose "displayName" is "Inbox"

to send an email to a recipient

Send an email through Outlook with the specified details and attachments.

It requires the following permissions on the scopes: Mail.ReadWrite, Mail.ReadWrite.Shared, Mail.Send

Input Concepts

Concept	Description	Type	Required	Default Value
email	The email to be sent	outlook email	Yes	(no default)
recipient	The recipient or recipients of the email	list of text or text	Yes	(no default)
cc recipients	The cc recipients of the email	list of text or text	No	(no default)
bcc recipients	The bcc recipients of the email	list of text or text	No	(no default)
attachments	The attachments to be sent with the email	file	No	(no default)
user	The user sending the email. Required for client credentials, otherwise, the user is the authenticated user.	office user	No	(no default)

Examples

Send an email to the specified recipients

create a json
use the above as the email
set the email's subject to "Meeting Reminder"
set the email's body to "Don't forget the meeting tomorrow at 10:00 AM"
the recipients are "[email protected]", "[email protected]"
send the email to the recipients

Send an email to the specified recipients as a user

...
use the first user as the user
create a json
use the above as the email
set the email's subject to "Meeting Reminder"
set the email's body to "Don't forget the meeting tomorrow at 10:00 AM"
the recipients are "[email protected]", "[email protected]"
send the email to the recipients
... the user is the user

Send an email to the specified recipients with custom cc recipients

create a json
use the above as the email
set the email's subject to "Meeting Reminder"
set the email's body to "Don't forget the meeting tomorrow at 10:00 AM"
the recipients are "[email protected]", "[email protected]"
the cc recipients are "[email protected]", "[email protected]"
send the email to the recipients
... the cc recipients is the cc recipients

Send an email to the specified recipients with custom bcc recipients

create a json
use the above as the email
set the email's subject to "Meeting Reminder"
set the email's body to "Don't forget the meeting tomorrow at 10:00 AM"
the recipients are "[email protected]", "[email protected]"
the bcc recipients are "[email protected]", "[email protected]"
send the email to the recipients
... the bcc recipients is the bcc recipients

Send an email to the specified recipients with attachments

...
use the above as the file
...
use the above as the other file
the attachments are the file, the other file
create a json
use the above as the email
set the email's subject to "Meeting Reminder"
set the email's body to "Don't forget the meeting tomorrow at 10:00 AM"
the recipients are "[email protected]", "[email protected]"
send the email to the recipients
... the attachments is the attachments

to set an entity's event's body to a text

Update the body of a calendar event.

It requires the following permissions on the application: Calendars.ReadWrite

Input Concepts

Concept	Description	Type	Required	Default Value
entity	The user's or group's calendar who owns the event	office group or office user	Yes	(no default)
event	The event that will be updated	outlook event	Yes	(no default)
text	The content of the body	text	Yes	(no default)

Examples

Update the body of the specified user event

get users from office365 whose mail is "[email protected]"
use the first entity as john
get john's events from outlook
use the first event as my event
set my event's body to "hello world"

Update the body of the specified group event

get groups from office365 whose mail is "[email protected]"
get the first group
get the above's events from outlook
get the first event
set the above's body to "hello world"

Concepts

Outlook email

An Outlook Email represents an email message in Microsoft Graph.

Field Name	Description	Type
id	The unique identifier for the email.	optional[text]
folder_id	The unique identifier for the folder containing the email.	optional[text]
subject	The subject of the email.	optional[text]
body	The body of the email.	optional[text]
recipients	The recipients of the email.	optional[list of text]
state	The state of the email (e.g., sent, received, draft, deleted, archived, unread).	optional[text]
sent_date_time	The date and time the email was sent.	optional[datetime]
received_date_time	The date and time the email was received.	optional[datetime]
sender	The sender of the email.	optional[text]
cc_recipients	The cc recipients of the email.	optional[list of text]
bcc_recipients	The bcc recipients of the email.	optional[list of text]
user_id	The id of the authenticated user making the requests. If it is None, the user is the using the "me" endpoints meaning delegated access.	optional[text]
has_attachments	Whether the email has attachments or not.	optional[boolean]

Outlook attachment

An Outlook Attachment represents a file or item attached to a calendar event in Microsoft Graph. It includes the attachment name and content type.

Field Name	Description	Type
attachment_id	The unique identifier for the attachment.	optional[text]
odata_type	The OData type of the attachment.	optional[text]
user_id	The user ID of the attachment.	optional[text]
name	The name of the attachment.	optional[text]
event_id	The ID of the event to which the attachment is attached.	optional[text]
email_id	The ID of the email to which the attachment is attached.	optional[text]

Outlook email folder

OutlookEmailFolder represents a folder within an Outlook mailbox, providing a way to organize and manage emails. It serves as a utility to group emails based on specific criteria, facilitating efficient email management and retrieval.

Field Name	Description	Type
id	The unique identifier for the folder.	optional[text]
name	The name of the folder.	optional[text]
user_id	The id of the authenticated user making the requests.	optional[text]

Office user

An Office User represents a user in the Microsoft Graph. It includes key user details such as display name,email address, and job title.

Field Name	Description	Type
id	The unique identifier for the user.	text
display_name	The name displayed in the address book for the user.	optional[text]
email_address	The user's email address (usually their user principal name).	optional[text]
job_title	The user's job title.	optional[text]

Outlook event

An Outlook Calendar Event is a scheduled occurrence within an Outlook calendar that is managed through theMicrosoft Graph API. The event object includes essential details such as the subject, start and end times, attendees, and location, and supports advanced features like reminders, recurrence patterns, and time zone adjustments.

Field Name	Description	Type
id	The unique identifier for the event. Read-only.	text
subject	The text of the event's subject line.	optional[text]
body_preview	The preview of the message associated with the event. It is in text format.	optional[text]
start	The start date, time, and time zone of the event. By default, the start time is in UTC.	optional[datetime]
end	The date, time, and time zone that the event ends. By default, the end time is in UTC.	optional[datetime]
location	The location of the event.	optional[outlook event location]
locations	The locations where the event is held or attended from. The location and locations properties always correspond with each other. If you update the location property, any prior locations in the locations collection would be removed and replaced by the new location value.	optional[list of outlook event location]
organizer	The organizer of the event.	optional[outlook email address]
attendees	The collection of attendees for the event.	optional[list of outlook event attendee]

Outlook event location

An Outlook Event Location represents a specific location associated with a calendar event or meeting inMicrosoft Graph. It includes properties like the display name, address, coordinates, and location type, enabling precise identification and use of locations within calendar-related functionalities.

Field Name	Description	Type
display_name	The name associated with the location.	optional[text]
email_address	Optional email address of the location.	optional[text]
type	The type of location. The possible values are: default, conferenceRoom, homeAddress, businessAddress,geoCoordinates, streetAddress, hotel, restaurant, localBusiness, postalAddress. Read-only.	optional[text]
uri	Optional URI representing the location.	optional[text]

Outlook email address

Represents an email address associated with a contact or calendar item inMicrosoft Graph. It includes only the name and email address fields.

Field Name	Description	Type
name	The display name associated with the email address.	optional[text]
address	The email address.	optional[text]

Outlook event attendee

An Outlook Event Attendee represents an attendee of a calendar event in Microsoft Graph. It includes the name, email address, attendee type, and response status fields.

Field Name	Description	Type
name	The display name associated with the attendee.	optional[text]
email_address	The email address of the attendee.	optional[text]
type	The type of attendee as a string. Possible values are: required, optional, resource.	optional[text]
status	The response status of the attendee as a string. Possible values are: accepted, declined, tentative, etc.	optional[text]
response_time	The datetime when the response was recorded.	optional[datetime]

Office group

An Office Group represents a group in the Microsoft Graph. It includes key user details such as display name,and email address.

Field Name	Description	Type
id	The unique identifier for the group.	text
display_name	The name displayed in the address book for the group.	optional[text]
email_address	The group's email address.	optional[text]