Microsoft Graph API Mail and Communication

This connector provides integration with Microsoft Graph API for managing mail and communication services, enabling automated workflows for email operations, contact management, and event scheduling.

Microsoft Graph API Mail and Communication connector enables seamless integration with Microsoft's email and communication services. It allows users to automate email management tasks such as creating contacts and events, deleting emails, and managing attachments directly within Swimlane Turbine. This integration empowers security teams to streamline communication-related workflows, enhance incident response, and maintain up-to-date contact information without manual intervention.

Configuration

Prerequisites

To utilize the Microsoft Graph API Mail and Communication connector, ensure you have the following prerequisites:

Client Credentials and Tenant ID authentication with these parameters:

URL: Endpoint for Microsoft Graph API

Client ID: Application ID registered in Azure AD

Client Secret: Key generated for the application in Azure AD

Tenant ID: Directory ID of the Azure AD tenant

Scope: Permissions required for the API calls

OAuth 2.0 Client Credentials with these parameters:

URL: Endpoint for Microsoft Graph API

Client ID: Application ID registered in Azure AD

Client Secret: Key generated for the application in Azure AD

Token URL: URL to retrieve the OAuth token

Scope: Permissions required for the API calls

Delegated Flow Authentication with these parameters:

URL: Endpoint for Microsoft Graph API

Tenant ID: Directory ID of the Azure AD tenant ... and so on

Authentication Methods

OAuth 2.0 client credentials authentication with these parameters:

url: Endpoint for Microsoft Graph API.

client_id: Application (client) ID registered in Azure AD.

client_secret: Client secret (key) generated for the application in Azure AD.

token_url: URL to retrieve the OAuth token.

scope: Permissions the app requires.

Password Grant (Delegated Authentication) for acting on behalf of a user:

url: Endpoint for Microsoft Graph API.

tenant_id: Directory ID of the Azure AD tenant.

oauth_un: User's username to authenticate.

oauth_pwd: User's password to authenticate.

oauth_cl_id: Application (client) ID registered in Azure AD.

oauth_cl_secret: Client secret (key) generated for the application in Azure AD.

login_url: Login URL. Default value is https://login.microsoftonline.com. (Optional).

scope: Permissions the app requires. Optional field. (Optional).

Asset credentials specific to your organization (Microsoft Graph API Asset - Tenant ID):

url: Endpoint for Microsoft Graph API.

client_ID: Application (client) ID registered in Azure AD.

client_Secret: Client secret (key) generated for the application in Azure AD.

tenant_id: Directory ID of the Azure AD tenant.

scope: Permissions the app requires.

Authentication for OAuth2 Refresh Token Grant credentials for Microsoft Graph API authentication

url: Endpoint for Microsoft Graph API.

client_ID: Application (client) ID registered in Azure AD.

client_Secret: Client secret (key) generated for the application in Azure AD.

refresh_token: Refresh Token.

scope: Permissions the app requires.

Capabilities

The Microsoft Graph API connector gives the ability to get and update security alerts, and modify user licenses and sessions.

Create Contact

Create Event

Delete Email

Expand and Get Item Properties Attached to Message

Export Email as EML

Forward Email

Get Email Attachments

Get Emails

Get Emails From Folder

Get Emails from a Folder

Get List of Child Folders

Get Manager Root Level

Move Email

Reply to Email

Send Email ... and so on

Asset Setup

Client Credential Flow Authentication

Authentication uses Azure application OAuth2. You will need an admin account in Azure to create the application.

Recommended Application Permissions (feel free use custom permissions if you only use certain actions):

User.ReadWrite.All

Directory.ReadWrite.All

Directory.AccessAsUser.All

Mail.ReadWrite

Mail.Send

AuditLog.Read.All

Mail.ReadBasic.All

User.ReadWrite.All

UserAuthenticationMethod.Read.All

UserAuthenticationMethod.ReadWrite.All

In order to set up the asset, you need the following:

Azure Application Client ID

Azure Application Client Secret

Azure Tenant ID

Steps to create the Azure app:

Go to the App Registration page in the Azure portal.

Click New Registration.

Enter a name for your new application and choose Accounts in this organizational directory only, then click Register at the bottom.

Navigate to the API permissions tab on the left navigation menu.

Select Add a permission.

Select Microsoft Graph.

Select Application permissions, then mark all the permissions you need for the actions you are using (See suggested permissions at the top of the asset setup section).

Click the Add permissions button at the bottom of the page.

Select Grant admin consent for your organization, then your permissions should look as below.

Navigate to the Certificates & secrets tab and select New client secret.

Fill out the description and expiration, then click the Add button at the bottom.

The Value of the secret you just created is the Client Secret needed for the Swimlane asset.

Navigate to the Overview tab on the left menu.

The Client ID and Tenant ID needed in the asset are shown on this page.

The Client ID, Tenant ID, and Client Secret described in the steps above are the credentials you need for the asset.

Password Flow (Delegated Auth)

Use Delegated Permissions, instead of Application Permissions, and generate Client ID, Tenant ID, and Client Secret as described in the above Client Credential Flow Authentication.

We also need an Username and a Password for this authentication.

Authentication flow for OAuth2 Refresh Token

Oauth 2.0 refresh token grant, which requires a Refresh Token,Tenant ID, Client ID and Client Secret. Use this auth with accounts which have MFA enabled. To generate a refresh token please follow the instructions below.

In step 3 of the above-mentioned setup instructions, please provide a Redirect URI and select the platform as 'Web', before clicking on Register at the the bottom.

Proceed with the remaining steps to generate 'Client ID', Tenant ID and Client Secret.

Add the permissions in Delegated Permissions.

The Swimlane team will provide a Python script and instructions on how to use the script to generate the Refresh Token.

Limit Access to specific mailboxes

Administrators who want to limit app access to specific mailboxes can create an application access policy by using the New-ApplicationAccessPolicy PowerShell cmdlet. For more information please see the article Limiting application permissions to specific Exchange Online mailboxes.

Action Setup

OData filters

Information on the filter input formatting can be found here.

Keep in mind that not specifying a folder as an input will result in the query affecting all possible folders. Example: If we want to ingest only unread emails, and we don't set the input "folder", we will ingest all unread emails from all folders, including "Deleted Items", "Junk", etc.

Well Known Folders

Well known folders can be used instead of Folder IDs for email actions. All well known folder names can be found here.

Sites Get Site

All the Sites actions require the site ID to be executed. The site ID can be obtained using the action Sites Get Site, in order to run the action the site_hostname and site_name are needed. This two values can be found in a site URL:

https://{site_hostname}.sharepoint.com/sites/{site_name}

For example if our site URL is https://swimlaneintegrations.sharepoint.com/sites/IntegrationsSite we should use:

site_hostname: swimlaneintegrations

site_name: IntegrationsSite

After the action execution you can find the Site ID on the ID output field.

Sites Create List

In order to create a list with its columns, use the input Columns. You can find all the possible values with its configuration on the following table.

Property name	Type	Description
boolean	booleanColumn	This column stores boolean values.
calculated	calculatedColumn	This column's data is calculated based on other columns.
choice	choiceColumn	This column stores data from a list of choices.
currency	currencyColumn	This column stores currency values.
dateTime	dateTimeColumn	This column stores DateTime values.
geolocation	geolocationColumn	This column stores a geolocation.
lookup	lookupColumn	This column's data is looked up from another source in the site.
number	numberColumn	This column stores number values.
personOrGroup	personOrGroupColumn	This column stores Person or Group values.
text	textColumn	This column stores text values.
validation	columnValidation	This column stores validation formula and message for the column.
hyperlinkOrPicture	hyperlinkOrPictureColumn	This column stores hyperlink or picture values.
term	termColumn	This column stores taxonomy terms.
thumbnail	thumbnailColumn	This column stores thumbnail values.
contentApprovalStatus	contentApprovalStatusColumn	This column stores content approval status.

For a complete version of this table please see the official column definition table.

Create List Column

Refer to the above table to get the Type properties and Column type input. The Type properties are documented within the links in the Type column.

Get list items

In order to use the filter input please refer to the OData filters section.

The column used to filter the output must be indexed, see the Microsoft documentation to add an index to a list.

Limitations

When using $filter and $orderby in the same query to get messages, make sure to specify properties in the following ways:

Properties that appear in $orderby must also appear in $filter.

Properties that appear in $orderby are in the same order as in $filter.

Properties that are present in $orderby appear in $filter before any properties that aren't.

Failing to do this results in the following error:

Error code: InefficientFilter

Error message: The restriction or sort order is too complex for this operation.

The Assign/Remove User License requires either the disabled plans and accompanying SKU IDs to assign licenses or the SKU ID of the license you want to remove.

The Get Security Alert has additional information it can return. There are a large number of fields that don't relate to many alerts, so they are not mapped; you can add them if desired.

Notes

An Introduction to Microsoft Graph API

Microsoft Graph REST API v1.0 reference

Query Parameters Documentation - OData V4

oauthlib Legacy Application client, this is sort of a hack to bypass manual login (typically required)

Configurations

Microsoft Graph API Asset - Tenant ID

Authenticates using Client Credentials and Tenant ID

Configuration Parameters

Parameter	Description	Type	Required
url	A URL to the target host.	string	Required
tenant_id	The Tenant ID.	string	Required
client_ID	The client ID	string	Required
client_Secret	The client secret.	string	Required
scope	List of permission scopes for this action.	array	Required
verify_ssl	Verify SSL certificate	boolean	Optional
http_proxy	A proxy to route requests through.	string	Optional

Password Grant (Delegated Authentication)

Authenticates on behalf of a user using oauth 2.0 credentials

Configuration Parameters

Parameter	Description	Type	Required
url	A URL to the target host.	string	Required
login_url		string	Optional
tenant_id		string	Required
oauth_un	The username for authentication	string	Required
oauth_pwd	The password for authentication	string	Required
oauth_cl_id	The client ID	string	Required
oauth_cl_secret	The client secret.	string	Required
scope	Permission scopes for this action.	array	Optional
verify_ssl	Verify SSL certificate	boolean	Optional
http_proxy	A proxy to route requests through.	string	Optional

Oauth 2.0 Client Credentials

Authenticates using oauth 2.0 client credentials

Configuration Parameters

Parameter	Description	Type	Required
url	A URL to the target host.	string	Required
token_url	Must start with https://login.microsoftonline.com/ and then continue with the tenant_id, and then be prepended with /oauth2/v2.0/token	string	Required
client_id	The client ID	string	Required
client_secret	The client secret.	string	Required
scope	List of permission scopes for this action.	array	Required
verify_ssl	Verify SSL certificate	boolean	Optional
http_proxy	A proxy to route requests through.	string	Optional

MS Graph OpenID Connect Refresh Token Grant

Authenticates using refresh token.

Configuration Parameters

Parameter	Description	Type	Required
url	A URL to the target host.	string	Required
cl_id	The client ID.	string	Required
cl_secret	The client secret.	string	Required
refresh_token	Refresh Token.	string	Optional
verify_ssl	Verify SSL certificate	boolean	Optional
http_proxy	A proxy to route requests through.	string	Optional

Actions

Create Contact

Adds a new contact to a specified folder in Microsoft Graph API using the provided 'id'. Requires path parameters and JSON body.

Endpoint

URL: /v1.0/users/{{id}}/contacts

Method: POST

Input

Argument Name	Type	Required	Description
path_parameters.id	string	Required	Parameters for the Create Contact action
givenName	string	Optional	The contact's given name.
surname	string	Optional	The contact's surname.
emailAddresses	array	Optional	The contact's email addresses.
emailAddresses.address	string	Optional	The email address of the contact.
emailAddresses.name	string	Optional	The display name of the contact.
businessPhones	array	Optional	The contact's business phone numbers.

Input Example

{"json_body":{"givenName":"Pavel","surname":"Bansky","emailAddresses":[{"address":"[email protected]","name":"Pavel Bansky"}],"businessPhones":["+1 732 555 0102"]},"path_parameters":{"id":"aaron.ooi_swimlane.com#EXT#@swimlaneintegrations.onmicrosoft.com"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
id	string	Unique identifier
createdDateTime	string	Time value
lastModifiedDateTime	string	Time value
displayName	string	Name of the resource

Output Example

{"id":"id-value","createdDateTime":"2015-11-09T02:14:32Z","lastModifiedDateTime":"2015-11-09T02:14:32Z","displayName":"Pavel Bansky"}

Create Event

Creates a new calendar event in a user's calendar identified by email address using the Microsoft Graph API.

Endpoint

URL: /v1.0/users/{{email_address}}/events

Method: POST

Input

Argument Name	Type	Required	Description
path_parameters.email_address	string	Required	Parameters for the Create Event action
headers	object	Optional	HTTP headers for the request
headers.Prefer	string	Optional	Specify the time zone for the start and end times in the response.
subject	string	Optional	The text of the event's subject line.
body	object	Optional	The body of the message associated with the event. It can be in HTML or text format.
body.contentType	string	Optional	The content of the item.
body.content	string	Optional	The type of the content.
start	object	Optional	The start date, time, and time zone of the event. By default, the start time is in UTC.
start.dateTime	string	Optional	A single point of time in a combined date and time representation (T; for example, 2017-08-29T04:00:00.0000000).
start.timeZone	string	Optional	Represents a time zone, for example, "Pacific Standard Time".
end	object	Optional	The date, time, and time zone that the event ends. By default, the end time is in UTC.
end.dateTime	string	Optional	A single point of time in a combined date and time representation (T; for example, 2017-08-29T04:00:00.0000000).
end.timeZone	string	Optional	Represents a time zone, for example, "Pacific Standard Time".
location	object	Optional	The location of the event.
location.displayName	string	Optional	The name associated with the location.
locations	array	Optional	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.
locations.displayName	string	Optional	The name associated with the location.
locations.locationType	string	Optional	The type of location.
locations.uniqueIdType	string	Optional	For internal use only.
locations.locationEmailAddress	string	Optional	Optional email address of the location.
locations.locationUri	string	Optional	Optional URI representing the location.
locations.uniqueId	string	Optional	For internal use only.
locations.address	object	Optional	The street address of the location.
locations.address.city	string	Optional	The city.
locations.address.countryOrRegion	string	Optional	The country or region. It's a free-format string value, for example, "United States".

Input Example

{"path_parameters":{"email_address":"[email protected]"},"headers":{"Prefer":"outlook.timezone=\"Pacific Standard Time\""}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
@odata.context	string	Response data
@odata.etag	string	Response data
id	string	Unique identifier
createdDateTime	string	Time value
lastModifiedDateTime	string	Time value
changeKey	string	Output field: changeKey
categories	array	Output field: categories
transactionId	object	Unique identifier
originalStartTimeZone	string	Output field: originalStartTimeZone
originalEndTimeZone	string	Output field: originalEndTimeZone
iCalUId	string	Unique identifier
uid	string	Unique identifier
reminderMinutesBeforeStart	number	Output field: reminderMinutesBeforeStart
isReminderOn	boolean	Output field: isReminderOn
hasAttachments	boolean	Output field: hasAttachments
subject	string	Output field: subject
bodyPreview	string	Request body data
importance	string	Output field: importance
sensitivity	string	Output field: sensitivity
isAllDay	boolean	Output field: isAllDay
isCancelled	boolean	Output field: isCancelled
isOrganizer	boolean	Output field: isOrganizer
responseRequested	boolean	Output field: responseRequested

Output Example

{"@odata.context":"string","@odata.etag":"string","id":"12345678-1234-1234-1234-123456789abc","createdDateTime":"string","lastModifiedDateTime":"string","changeKey":"string","categories":["string"],"transactionId":{},"originalStartTimeZone":"string","originalEndTimeZone":"string","iCalUId":"string","uid":"string","reminderMinutesBeforeStart":123,"isReminderOn":true,"hasAttachments":true}

Delete Email

Permanently removes an email from a specified mailbox by using the email address and email ID through Microsoft Graph API.

Endpoint

URL: /v1.0/users/{{email_address}}/messages/{{email_id}}

Method: DELETE

Input

Argument Name	Type	Required	Description
path_parameters.email_address	string	Required	The account associated with the email
path_parameters.email_id	string	Required	The ID of the email

Input Example

{"path_parameters":{"email_address":"string","email_id":"string"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
response_text	string	Output field: response_text

Output Example

{"response_text":"string"}

Expand and Get Item Properties Attached to Message

Retrieves properties of an email attachment using the provided email address, email ID, and attachment ID in Microsoft Graph API.

Endpoint

URL: /v1.0/users/{{email_address}}/messages/{{email_id}}/attachments/{{attachment_id}}/

Method: GET

Input

Argument Name	Type	Required	Description
path_parameters.email_address	string	Required	The account associated with the email.
path_parameters.email_id	string	Required	The ID of the email to retrieve attachments from.
path_parameters.attachment_id	string	Required	Attachment ID.
remove_content_bytes	boolean	Optional	Remove Content Bytes from the response.
parameters.$expand	string	Optional	To get the properties of an item attachment (contact, event, or message).

Input Example

{"parameters":{"$expand":"microsoft.graph.itemattachment/item"},"path_parameters":{"email_address":"[email protected]","email_id":"AAMkADMxZmU3ZWQ4LTMzNGItNGY3ZC1iM2UxLWM3MDQzOGVjMzlkNwBGAAAAAAAHYPwuVwMWSrFeyLv6XHMzBwCBJRT9-oiDTLpLg45RvPkCAAAAAAEMAACBJRT9-oiDTLpLg45RvPkCAAQxsRLaAAA=","attachment_id":"AAMkADMxZmU3ZWQ4LTMzNGItNGY3ZC1iM2UxLWM3MDQzOGVjMzlkNwBGAAAAAAAHYPwuVwMWSrFeyLv6XHMzBwCBJRT9-oiDTLpLg45RvPkCAAAAAAEMAACBJRT9-oiDTLpLg45RvPkCAAQxsRLaAAABEgAQABYpe5LWcI5Cg91dH8N8e_s="},"remove_content_bytes":true}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
@odata.context	string	Response data
@odata.type	string	Response data
id	string	Unique identifier
lastModifiedDateTime	string	Time value
name	string	Name of the resource
contentType	object	Type of the resource
size	number	Output field: size
isInline	boolean	Output field: isInline
[email protected]	string	Response data
[email protected]	string	Response data
item	object	Output field: item
[email protected]	string	Response data
item.id	string	Unique identifier
item.createdDateTime	string	Time value
item.lastModifiedDateTime	string	Time value
item.receivedDateTime	string	Time value
item.sentDateTime	string	Time value
item.hasAttachments	boolean	Output field: item.hasAttachments
item.internetMessageId	string	Unique identifier
item.subject	string	Output field: item.subject
item.bodyPreview	string	Request body data
item.importance	string	Output field: item.importance
item.conversationId	string	Unique identifier

Output Example

{"@odata.context":"string","@odata.type":"string","id":"12345678-1234-1234-1234-123456789abc","lastModifiedDateTime":"string","name":"Example Name","contentType":{},"size":123,"isInline":true,"[email protected]":"string","[email protected]":"string","item":{"@odata.type":"string","id":"12345678-1234-1234-1234-123456789abc","createdDateTime":"string","lastModifiedDateTime":"string","receivedDateTime":"string","sentDateTime":"string","hasAttachments":true,"internetMessageId":"stri...

Export Email as EML

Exports an email as an EML file by using a specified ID and email address via the Microsoft Graph API.

Endpoint

URL: /v1.0/users/{{email_address}}/messages/{{id}}/$value

Method: GET

Input

Argument Name	Type	Required	Description
path_parameters.email_address	string	Required	Parameters for the Export Email as EML action
path_parameters.id	string	Required	Parameters for the Export Email as EML action
filename	string	Optional	Filename for the generated eml file. Default - .eml

Input Example

{"path_parameters":{"email_address":"[email protected]","id":"KH5kvS_JT3JBwCGdzOUGK1yRYre5W5mstJUAAAAAAEMAACGdzOUGK1yRYre5W5mstJUAAOQSnsJAAA="}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
file	object	Attachments
file.file	string	Output field: file.file
file.file_name	string	Name of the resource

Output Example

{"file":{"file":"string","file_name":"Example Name"}}

Forward Email

Forwards an email from a specified address to designated recipients with an optional comment using Microsoft Graph API.

Endpoint

URL: /v1.0/users/{{email_address}}/messages/{{email_id}}/forward

Method: POST

Input

Argument Name	Type	Required	Description
path_parameters.email_address	string	Required	The account associated with the email
path_parameters.email_id	string	Required	The ID of the email
comment	string	Optional	A comment to include. Can be an empty string.
toRecipients	array	Optional	The list of direct recipient objects.
toRecipients.emailAddress	object	Required	Parameter for Forward Email
toRecipients.emailAddress.address	string	Required	Parameter for Forward Email
toRecipients.emailAddress.name	string	Optional	Name of the resource

Input Example

{"path_parameters":{"email_address":"string","email_id":"string"},"comment":"string","toRecipients":[{"emailAddress":{"address":"string","name":"Example Name"}}]}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
response_text	string	Output field: response_text

Output Example

{"response_text":"string"}

Get Email Attachments

Retrieve all attachments from a specified email in Microsoft Graph API using the provided email address and email ID.

Endpoint

URL: /v1.0/users/{{email_address}}/messages/{{email_id}}/attachments

Method: GET

Input

Argument Name	Type	Required	Description
path_parameters.email_address	string	Required	The account associated with the email
path_parameters.email_id	string	Required	The ID of the email to retrieve attachments from
parameters.$expand	string	Optional	To get the properties of an item attachment (contact, event, or message).
remove_content_bytes	boolean	Optional	The account associated with the email

Input Example

{"parameters":{"$expand":"microsoft.graph.itemattachment/item"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
attachments	array	Output field: attachments
attachments.0	object	Output field: attachments.0
attachments.0.file_name	string	Name of the resource
attachments.0.file	string	Output field: attachments.0.file
@odata.context	string	Response data
value	array	Value for the parameter
[email protected]	string	Response data
[email protected]	string	Response data
value.id	string	Unique identifier
value.lastModifiedDateTime	string	Value for the parameter
value.name	string	Name of the resource
value.contentType	string	Type of the resource
value.size	number	Value for the parameter
value.isInline	boolean	Value for the parameter
value.contentId	object	Unique identifier
value.contentLocation	object	Value for the parameter

Output Example

{"@odata.context":"https://graph.microsoft.com/v1.0/$metadata#users('integrations%40swimlaneintegra...","value":[{"@odata.type":"#microsoft.graph.fileAttachment","@odata.mediaContentType":"image/png","id":"AAMkADMxZmU3ZWQ4LTMzNGItNGY3ZC1iM2UxLWM3MDQzOGVjMzlkNwBGAAAAAAAHYPwuVwMWSrFeyLv6...","lastModifiedDateTime":"2022-05-11T04:55:25Z","name":"test_file.png","contentType":"image/png","size":1569,"isInline":false,"contentId":null,"contentLocation":null}]}

Get Emails

Retrieves a list of emails for a given 'email_address' using the Microsoft Graph API, providing access to user messages.

Endpoint

URL: /v1.0/users/{{email_address}}/messages

Method: GET

Input

Argument Name	Type	Required	Description
path_parameters.email_address	string	Required	The account associated with the email
parameters.count	string	Optional	Include a count of the total number of items in a collection alongside the page of data values returned from Microsoft Graph
parameters.filter	string	Optional	Use the $filter query parameter to retrieve just a subset of a collection. For guidance on using $filter, see https://learn.microsoft.com/en-us/graph/filter-query-parameter
parameters.orderby	string	Optional	To sort the results in ascending or descending order, append either asc or desc to the field name, separated by a space.
parameters.top	number	Optional	Sets the page size of results
headers	object	Optional	HTTP headers for the request
headers.Prefer	string	Optional	The format of the body and uniqueBody properties to be returned in. Values can be "text" or "html". A Preference-Applied header is returned as confirmation if this Prefer header is specified. If the header is not specified, the body and uniqueBody properties are returned in HTML format.

Input Example

{"headers":{"Prefer":"outlook.body-content-type='text'"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
@odata.context	string	Response data
@odata.count	number	Response data
value	array	Value for the parameter
[email protected]	string	Response data
value.id	string	Unique identifier
value.createdDateTime	string	Value for the parameter
value.lastModifiedDateTime	string	Value for the parameter
value.changeKey	string	Value for the parameter
value.categories	array	Value for the parameter
value.categories.file_name	string	Name of the resource
value.categories.file	string	Value for the parameter
value.receivedDateTime	string	Value for the parameter
value.sentDateTime	string	Value for the parameter
value.hasAttachments	boolean	Value for the parameter
value.internetMessageId	string	Unique identifier
value.subject	string	Value for the parameter
value.bodyPreview	string	Request body data
value.importance	string	Value for the parameter
value.parentFolderId	string	Unique identifier
value.conversationId	string	Unique identifier
value.conversationIndex	string	Value for the parameter
value.isDeliveryReceiptRequested	object	Value for the parameter
value.isReadReceiptRequested	boolean	Value for the parameter

Output Example

{"@odata.context":"string","@odata.count":123,"value":[{"@odata.etag":"string","id":"12345678-1234-1234-1234-123456789abc","createdDateTime":"string","lastModifiedDateTime":"string","changeKey":"string","categories":[],"receivedDateTime":"string","sentDateTime":"string","hasAttachments":true,"internetMessageId":"string","subject":"string","bodyPreview":"string","importance":"string","parentFolderId":"string","conversationId":"string"}],"@odata.nextLink":"string"}

Get Emails from a Folder

Retrieve emails from a specified folder in a user's mailbox on Microsoft Graph API using the email address and folder ID.

Endpoint

URL: /v1.0/users/{{email_address}}/mailFolders/{{folder_id}}/messages

Method: GET

Input

Argument Name	Type	Required	Description
path_parameters.email_address	string	Required	The account associated with the email
path_parameters.folder_id	string	Required	The Folder to get emails from
parameters.count	string	Optional	Include a count of the total number of items in a collection alongside the page of data values returned from Microsoft Graph
parameters.filter	string	Optional	Use the $filter query parameter to retrieve just a subset of a collection. For guidance on using $filter, see https://learn.microsoft.com/en-us/graph/filter-query-parameter
parameters.orderby	string	Optional	To sort the results in ascending or descending order, append either asc or desc to the field name, separated by a space.
parameters.top	number	Optional	Sets the page size of results
headers	object	Optional	HTTP headers for the request
headers.Prefer	string	Optional	The format of the body and uniqueBody properties to be returned in. Values can be "text" or "html". A Preference-Applied header is returned as confirmation if this Prefer header is specified. If the header is not specified, the body and uniqueBody properties are returned in HTML format.

Input Example

{"headers":{"Prefer":"outlook.body-content-type='text'"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
@odata.context	string	Response data
@odata.count	number	Response data
value	array	Value for the parameter
[email protected]	string	Response data
value.id	string	Unique identifier
value.createdDateTime	string	Value for the parameter
value.lastModifiedDateTime	string	Value for the parameter
value.changeKey	string	Value for the parameter
value.categories	array	Value for the parameter
value.categories.file_name	string	Name of the resource
value.categories.file	string	Value for the parameter
value.receivedDateTime	string	Value for the parameter
value.sentDateTime	string	Value for the parameter
value.hasAttachments	boolean	Value for the parameter
value.internetMessageId	string	Unique identifier
value.subject	string	Value for the parameter
value.bodyPreview	string	Request body data
value.importance	string	Value for the parameter
value.parentFolderId	string	Unique identifier
value.conversationId	string	Unique identifier
value.conversationIndex	string	Value for the parameter
value.isDeliveryReceiptRequested	object	Value for the parameter
value.isReadReceiptRequested	boolean	Value for the parameter

Output Example

Get Emails From Folder

Retrieve emails from a specified folder in a user's Microsoft Graph API account using the email address and folder ID.

Endpoint

URL: /v1.0/users/{{email_address}}/mailFolders/{{folder_id}}/messages

Method: GET

Input

Argument Name	Type	Required	Description
path_parameters.email_address	string	Required	The account associated with the email
path_parameters.folder_id	string	Required	The folder ID, or a well-known folder name. For a list of supported well-known folder names, see https://learn.microsoft.com/en-us/graph/api/resources/mailfolder?view=graph-rest-1.0
parameters.count	string	Optional	Include a count of the total number of items in a collection alongside the page of data values returned from Microsoft Graph
parameters.filter	string	Optional	Use the $filter query parameter to retrieve just a subset of a collection. For guidance on using $filter, see https://learn.microsoft.com/en-us/graph/filter-query-parameter
parameters.orderby	string	Optional	To sort the results in ascending or descending order, append either asc or desc to the field name, separated by a space.
parameters.top	number	Optional	Sets the page size of results

Input Example

{"path_parameters":{"email_address":"string","folder_id":"string"},"parameters":{"count":"false","filter":"string","orderby":"string","top":123}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
@odata.context	string	Response data
@odata.count	number	Response data
value	array	Value for the parameter
[email protected]	string	Response data
value.id	string	Unique identifier
value.createdDateTime	string	Value for the parameter
value.lastModifiedDateTime	string	Value for the parameter
value.changeKey	string	Value for the parameter
value.categories	array	Value for the parameter
value.categories.file_name	string	Name of the resource
value.categories.file	string	Value for the parameter
value.receivedDateTime	string	Value for the parameter
value.sentDateTime	string	Value for the parameter
value.hasAttachments	boolean	Value for the parameter
value.internetMessageId	string	Unique identifier
value.subject	string	Value for the parameter
value.bodyPreview	string	Request body data
value.importance	string	Value for the parameter
value.parentFolderId	string	Unique identifier
value.conversationId	string	Unique identifier
value.conversationIndex	string	Value for the parameter
value.isDeliveryReceiptRequested	boolean	Value for the parameter
value.isReadReceiptRequested	boolean	Value for the parameter

Output Example

Get List of Child Folders

Retrieve a list of child folders from a specified folder in Microsoft Graph API, using the provided email address and folder ID.

Endpoint

URL: /v1.0/users/{{email_address}}/mailFolders/{{folder_id}}/childFolders

Method: GET

Input

Argument Name	Type	Required	Description
path_parameters.email_address	string	Required	The account associated with the email.
path_parameters.folder_id	string	Required	The mailFolder's unique identifier.
parameters.includeHiddenFolders	boolean	Optional	To include hidden child folders in the response.

Input Example

{"parameters":{"includeHiddenFolders":true},"path_parameters":{"email_address":"[email protected]","folder_id":"AQMkADAwATNiZmYAZC1jODNkLTI5MjUtMDACLTAwCgAuAAAD4NNqHYKaBkOb7N4GZr"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
@odata.context	string	Response data
value	array	Value for the parameter
value.id	string	Unique identifier
value.displayName	string	Name of the resource
value.parentFolderId	string	Unique identifier
value.childFolderCount	number	Value for the parameter
value.unreadItemCount	number	Value for the parameter
value.totalItemCount	number	Value for the parameter
value.sizeInBytes	number	Value for the parameter
value.isHidden	boolean	Unique identifier

Output Example

{"@odata.context":"string","value":[{"id":"12345678-1234-1234-1234-123456789abc","displayName":"Example Name","parentFolderId":"string","childFolderCount":123,"unreadItemCount":123,"totalItemCount":123,"sizeInBytes":123,"isHidden":true}]}

Get Manager Root Level

Retrieve the direct manager's root level details in Microsoft Graph API using a user's ID or userPrincipalName.

Endpoint

URL: v1.0/users/{{id|userPrincipalName}}

Method: GET

Input

Argument Name	Type	Required	Description
`path_parameters.id	userPrincipalName`	string	Required	The user's ID or UserPrincipalName
headers	object	Optional	HTTP headers for the request
headers.ConsistencyLevel	string	Optional	Required when the request includes the $levels=n in the $expand query parameter.
parameters.$levels	string	Optional	The n value of $levels can be max (to return all managers) or a number between 1 and 1000.
parameters.$select	string	Optional	To select the individual Manager's properties.
parameters.$expand	string	Optional	To retrieve the Manager's Information for specified Levels, Selected ID and DisplayName.

Input Example

{"parameters":{"$levels":"max","$select":"id","$expand":"manager($levels=max;$select=id,displayName)"},"path_parameters":{"id|userPrincipalName":"357b1656-cfad-4b3f-a4c4-4a03bdcd6468"},"headers":{"ConsistencyLevel":"eventual"}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
@odata.context	string	Response data
businessPhones	array	Output field: businessPhones
businessPhones.file_name	string	Name of the resource
businessPhones.file	string	Output field: businessPhones.file
displayName	string	Name of the resource
givenName	object	Name of the resource
jobTitle	object	Output field: jobTitle
mail	string	Output field: mail
mobilePhone	object	Output field: mobilePhone
officeLocation	object	Output field: officeLocation
preferredLanguage	object	Output field: preferredLanguage
surname	object	Name of the resource
userPrincipalName	string	Name of the resource
id	string	Unique identifier

Output Example

{"@odata.context":"string","businessPhones":[{"file_name":"Example Name","file":"string"}],"displayName":"Example Name","givenName":{},"jobTitle":{},"mail":"string","mobilePhone":{},"officeLocation":{},"preferredLanguage":{},"surname":{},"userPrincipalName":"Example Name","id":"12345678-1234-1234-1234-123456789abc"}

Move Email

Relocate an email to a specified folder in a user's mailbox on Microsoft Graph API using their email address, email ID, and destination ID.

Endpoint

URL: /v1.0/users/{{email_address}}/messages/{{email_id}}/move

Method: POST

Input

Argument Name	Type	Required	Description
path_parameters.email_address	string	Required	The account associated with the email
path_parameters.email_id	string	Required	The ID of the email
destinationId	string	Optional	The destination folder ID, or a well-known folder name

Input Example

{"path_parameters":{"email_address":"string","email_id":"string"},"destinationId":"string"}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
@odata.context	string	Response data
@odata.etag	string	Response data
id	string	Unique identifier
createdDateTime	string	Time value
lastModifiedDateTime	string	Time value
changeKey	string	Output field: changeKey
categories	array	Output field: categories
categories.file_name	string	Name of the resource
categories.file	string	Output field: categories.file
receivedDateTime	string	Time value
sentDateTime	string	Time value
hasAttachments	boolean	Output field: hasAttachments
internetMessageId	string	Unique identifier
subject	string	Output field: subject
bodyPreview	string	Request body data
importance	string	Output field: importance
parentFolderId	string	Unique identifier
conversationId	string	Unique identifier
conversationIndex	string	Output field: conversationIndex
isDeliveryReceiptRequested	object	Output field: isDeliveryReceiptRequested
isReadReceiptRequested	boolean	Output field: isReadReceiptRequested
isRead	boolean	Output field: isRead
isDraft	boolean	Output field: isDraft

Output Example

{"@odata.context":"string","@odata.etag":"string","id":"12345678-1234-1234-1234-123456789abc","createdDateTime":"string","lastModifiedDateTime":"string","changeKey":"string","categories":[{"file_name":"Example Name","file":"string"}],"receivedDateTime":"string","sentDateTime":"string","hasAttachments":true,"internetMessageId":"string","subject":"string","bodyPreview":"string","importance":"string","parentFolderId":"string"}

Reply to Email

Send a custom reply to an email by specifying the recipient's address and email ID using Microsoft Graph API.

Endpoint

URL: /v1.0/users/{{email_address}}/messages/{{email_id}}/reply

Method: POST

Input

Argument Name	Type	Required	Description
path_parameters.email_address	string	Required	The account associated with the email
path_parameters.email_id	string	Required	The ID of the email
comment	string	Optional	A comment to include. Can be an empty string.
saveToSentItems	boolean	Optional	Indicates whether to save the message in Sent Items. Specify it only if the parameter is false; default is true. Optional.
message	object	Optional	The message to send
message.subject	string	Optional	The subject of the email
message.body	object	Optional	The body of the message. It can be in HTML or text format.
message.body.content	string	Optional	The content of the item
message.body.contentType	string	Optional	The type of the content. Possible values are text and html.
message.sender	object	Optional	The account that is actually used to generate the message. In most cases, this value is the same as the from property
message.sender.address	string	Required	Response message
message.sender.name	string	Optional	Name of the resource
message.replyTo	array	Optional	The email addresses to use when replying.
message.replyTo.emailAddress	object	Required	Response message
message.replyTo.emailAddress.address	string	Required	Response message
message.replyTo.emailAddress.name	string	Optional	Name of the resource
message.toRecipients	array	Optional	The list of direct recipient objects.
message.toRecipients.emailAddress	object	Required	Response message
message.toRecipients.emailAddress.address	string	Required	Response message
message.toRecipients.emailAddress.name	string	Optional	Name of the resource
message.ccRecipients	array	Optional	The list of CC recipient objects.
message.ccRecipients.emailAddress	object	Required	Response message
message.ccRecipients.emailAddress.address	string	Required	Response message
message.ccRecipients.emailAddress.name	string	Optional	Name of the resource
message.bccRecipients	array	Optional	The list of BCC recipient objects.

Input Example

{"path_parameters":{"email_address":"string","email_id":"string"},"comment":"string","saveToSentItems":true,"message":{"subject":"string","body":{"content":"string","contentType":"string"},"sender":{"address":"string","name":"Example Name"},"replyTo":[{"emailAddress":{"address":"string","name":"Example Name"}}],"toRecipients":[{"emailAddress":{"address":"string","name":"Example Name"}}],"ccRecipients":[{"emailAddress":{"address":"string","name":"Example Name"}}],"bccRecipients":[{"emailAddress":{"address":"string","name":"Example Name"}}],"attachments":[{"contentBytes":"string","name":"Example Name","@odata.type":"#microsoft.graph.fileAttachment","contentType":"text/plain"}]}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
response_text	string	Output field: response_text

Output Example

{"response_text":"string"}

Send Email

Sends a custom email through Microsoft Graph API using the recipient's email address and provided message content.

Endpoint

URL: /v1.0/users/{{email_address}}/sendMail

Method: POST

Input

Argument Name	Type	Required	Description
path_parameters.email_address	string	Required	The account associated with the email
saveToSentItems	boolean	Optional	Indicates whether to save the message in Sent Items. Specify it only if the parameter is false; default is true. Optional.
message	object	Optional	The message to send
message.subject	string	Optional	The subject of the email
message.body	object	Optional	The body of the message. It can be in HTML or text format.
message.body.content	string	Optional	The content of the item
message.body.contentType	string	Optional	The type of the content. Possible values are text and html.
message.replyTo	array	Optional	The email addresses to use when replying.
message.replyTo.emailAddress	object	Required	Response message
message.replyTo.emailAddress.address	string	Required	Response message
message.replyTo.emailAddress.name	string	Optional	Name of the resource
message.toRecipients	array	Required	The list of direct recipient objects.
message.toRecipients.emailAddress	object	Required	Response message
message.toRecipients.emailAddress.address	string	Required	Response message
message.toRecipients.emailAddress.name	string	Optional	Name of the resource
message.ccRecipients	array	Optional	The list of CC recipient objects.
message.ccRecipients.emailAddress	object	Required	Response message
message.ccRecipients.emailAddress.address	string	Required	Response message
message.ccRecipients.emailAddress.name	string	Optional	Name of the resource
message.bccRecipients	array	Optional	The list of BCC recipient objects.
message.bccRecipients.emailAddress	object	Required	Response message
message.bccRecipients.emailAddress.address	string	Required	Response message
message.bccRecipients.emailAddress.name	string	Optional	Name of the resource
message.attachments	array	Optional	Items attached to this email
message.attachments.contentBytes	string	Optional	Response content

Input Example

{"path_parameters":{"email_address":"string"},"saveToSentItems":true,"message":{"subject":"string","body":{"content":"string","contentType":"string"},"replyTo":[{"emailAddress":{"address":"string","name":"Example Name"}}],"toRecipients":[{"emailAddress":{"address":"string","name":"Example Name"}}],"ccRecipients":[{"emailAddress":{"address":"string","name":"Example Name"}}],"bccRecipients":[{"emailAddress":{"address":"string","name":"Example Name"}}],"attachments":[{"contentBytes":"string","name":"Example Name","@odata.type":"#microsoft.graph.fileAttachment","contentType":"text/plain"}]}}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
response_text	string	Output field: response_text

Output Example

{"response_text":"string"}

Update Message

Updates specific email properties in Microsoft Graph API using a unique userPrincipalName and message ID.

Endpoint

URL: /users/{{userPrincipalName}}/messages/{{id}}

Method: PATCH

Input

Argument Name	Type	Required	Description
path_parameters.userPrincipalName	string	Required	The email address of the user.
path_parameters.id	string	Required	The unique identifier of the message.
bccRecipients	array	Optional	The list of BCC recipient objects.
bccRecipients.emailAddress	object	Required	Parameter for Update Message
bccRecipients.emailAddress.address	string	Required	Parameter for Update Message
bccRecipients.emailAddress.name	string	Optional	Name of the resource
body	object	Optional	The body of the message. Updatable only if isDraft = true.
body.contentType	string	Required	Request body data
body.content	string	Required	Request body data
categories	array	Optional	The categories associated with the message.
ccRecipients	array	Optional	The Cc recipients for the message.
ccRecipients.emailAddress	object	Required	Parameter for Update Message
ccRecipients.emailAddress.address	string	Required	Parameter for Update Message
ccRecipients.emailAddress.name	string	Optional	Name of the resource
flag	object	Optional	The flag value that indicates the status, start date, due date, or completion date for the message.
flag.flagStatus	string	Optional	Status value
flag.startDateTime	object	Optional	Time value
flag.startDateTime.dateTime	string	Optional	Time value
flag.startDateTime.timeZone	string	Optional	Parameter for Update Message
flag.dueDateTime	object	Optional	Time value
flag.dueDateTime.dateTime	string	Optional	Time value
flag.dueDateTime.timeZone	string	Optional	Parameter for Update Message
flag.completedDateTime	object	Optional	Time value
flag.completedDateTime.dateTime	string	Optional	Time value
flag.completedDateTime.timeZone	string	Optional	Parameter for Update Message

Input Example

{"path_parameters":{"userPrincipalName":"Example Name","id":"12345678-1234-1234-1234-123456789abc"},"bccRecipients":[{"emailAddress":{"address":"string","name":"Example Name"}}],"body":{"contentType":"string","content":"string"},"categories":["string"],"ccRecipients":[{"emailAddress":{"address":"string","name":"Example Name"}}],"flag":{"flagStatus":"active","startDateTime":{"dateTime":"string","timeZone":"string"},"dueDateTime":{"dateTime":"string","timeZone":"string"},"completedDateTime":{"dateTime":"string","timeZone":"string"}},"from":{"emailAddress":{"address":"string","name":"Example Name"}},"importance":"string","inferenceClassification":"string","internetMessageId":"string","isDeliveryReceiptRequested":true,"isRead":true,"isReadReceiptRequested":true,"multiValueExtendedProperties":[{"id":"12345678-1234-1234-1234-123456789abc","value":["string"]}],"replyTo":[{"emailAddress":{"address":"string","name":"Example Name"}}],"sender":{"emailAddress":{"address":"string","name":"Example Name"}},"singleValueExtendedProperties":[{"id":"12345678-1234-1234-1234-123456789abc","value":"string"}],"subject":"string","toRecipients":[{"emailAddress":{"address":"string","name":"Example Name"}}]}

Output

Parameter	Type	Description
status_code	number	HTTP status code of the response
reason	string	Response reason phrase
receivedDateTime	string	Time value
sentDateTime	string	Time value
hasAttachments	boolean	Output field: hasAttachments
subject	string	Output field: subject
body	object	Request body data
body.contentType	string	Request body data
body.content	string	Request body data
bodyPreview	string	Request body data
inferenceClassification	string	Output field: inferenceClassification

Output Example

{"receivedDateTime":"datetime-value","sentDateTime":"datetime-value","hasAttachments":true,"subject":"subject-value","body":{"contentType":"","content":"content-value"},"bodyPreview":"bodyPreview-value","inferenceClassification":"other"}

Response Headers

Header	Description	Example
Cache-Control	Directives for caching mechanisms	no-cache
client-request-id	HTTP response header: client-request-id	946c11c2-b6ad-4cf5-b749-e51d5a886a3e
Content-Encoding	HTTP response header: Content-Encoding	gzip
Content-Length	The length of the response body in bytes	0
Content-Type	The media type of the resource	application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8
Date	The date and time at which the message was originated	Tue, 08 Nov 2022 01:06:18 GMT
Location	The URL to redirect a page to	https://graph.microsoft.com/v1.0/users('[email protected]')/events('AAMkADMxZmU3ZWQ4LTMzNGItNGY3ZC1iM2UxLWM3MDQzOGVjMzlkNwBGAAAAAAAHYPwuVwMWSrFeyLv6XHMzBwCBJRT9-oiDTLpLg45RvPkCAAAAAAENAACBJRT9-oiDTLpLg45RvPkCAASiLBybAAA=')
OData-Version	HTTP response header: OData-Version	4.0
request-id	HTTP response header: request-id	946c11c2-b6ad-4cf5-b749-e51d5a886a3e
Strict-Transport-Security	HTTP response header: Strict-Transport-Security	max-age=31536000
Transfer-Encoding	HTTP response header: Transfer-Encoding	chunked
Vary	HTTP response header: Vary	Accept-Encoding
x-ms-ags-diagnostic	HTTP response header: x-ms-ags-diagnostic	{"ServerInfo":{"DataCenter":"South India","Slice":"E","Ring":"2","ScaleUnit":"000","RoleInstance":"MA1PEPF000095F4"}}
x-ms-resource-unit	HTTP response header: x-ms-resource-unit	2