Office 365

LAST UPDATED: APR 15, 2025

Overview

Microsoft Office 365 service consists of a number of products and services. Outlook is a messaging communication hub in Microsoft 365. Using Microsoft Graph API, users can get authorized access to Outlook mail data in a personal or organization account.

D3 SOAR is providing REST operations to function with Office 365.

Office 365 is available for use in:

D3 SOAR	V12.7.83.0+
Category	Email Messaging
Deployment Options	Option II, Option IV

Connection

To connect Office 365 from D3 SOAR, follow this part to collect the required information below:

READER NOTE

When Authorization Code is selected as the Grant Type, only the signed-in user's mailbox can be accessed. To access mailboxes of other users in the organization, select Client Credentials as the Grant Type.

Parameter	Description	Example
Default
Microsoft 365 Environment	The Microsoft 365 cloud environment used for the API connection. This selection depends on the compliance and security requirements of the user’s organization. Available options are: Commercial & GCC Environment GCC High Environment (Level 4) DoD Environment (Level 5) By default, the value is set to Commercial & GCC Environment. Refer to the Office 365 GCC High and DoD documentation for more information on the GCC High Environment (Level 4) and DoD Environment (Level 5) options which offer higher levels of security and compliance.	Commercial & GCC Environment
Tenant ID	The tenant ID to authenticate the API connection.	*****
Grant Type	The grant type to authenticate the API connection. If users select Authorization Code as the Grant Type, then they can only access the signed-in user's mailbox. To access any other user's email box in the organization, select Client Credentials.	Client Credentials
API Version	The version of the API to use for the connection.	v1.0
Grant Type: Client Credentials
Client ID	The client ID to authenticate the API connection.	*****
Client Secret	The client secret to authenticate the API connection.	*****
Grant Type: Authorization Code
Client ID	The client ID to authenticate the API connection.	*****
Client Secret	The client secret to authenticate the API connection.	*****
Scope	The scopes used for the OAuth2.0 with the authorization code grant type.	offline_access https://graph.microsoft.com/mail.ReadWrite https://graph.microsoft.com/mail.Send
Authorization Code	The authorization code for the OAuth2.0 authentication. Click the "Get Authorization" button on the Connection page to automatically generate an authorization code.	*****
Callback URL	The callback URL is used for OAuth2.0 with the grant type of authorization code. Add this URL to the user’s app's Redirect URIs. In the Azure portal, navigate to Microsoft Entra ID Protection > App Registrations > Your App > Authentication.	*****
Refresh Token	The refresh token for authentication with the grant type of authorization code. Click the "Get Refresh Token" button on the Connection page to automatically generate a refresh token. This parameter is read-only and auto-generated.	*****

Permission Requirements

Each endpoint in the Office 365 API requires a certain permission scope. The following are required scopes for the commands in this integration:

READER NOTE

When using Authorization Code as the grant type, corresponding Delegated Permissions are required to execute commands.
When using Client Credentials as the grant type, corresponding Application Permissions are required to execute commands.
When the account is using the Delegated Permission Type, all commands require the offline_access permission. This permission, a standard OIDC scope, is required for the app to obtain a refresh token. More information can be found at Get access on behalf of a user - Microsoft Graph.

Command	Permission	Roles	API References
Delete Email Message	Delegated Mail.ReadWrite offline_access	N/A	Delete message - Microsoft Graph v1.0
	Application Mail.ReadWrite
Delete User Accounts	Delegated User.ReadWrite.All offline_access Directory.AccessAsUser.All See the corresponding note in the Roles column	Delegated The calling user must have at least the User Administrator role. To delete users with Privileged Authentication Administrator roles in delegated scenarios, the app must be assigned the Directory.AccessAsUser.All delegated permission, and the calling user must have a higher privileged administrator role. Refer to the Privileged Role Permissions Matrix for more information.	Delete a user - Microsoft Graph API
	Application User.ReadWrite.All
		Application The calling user must have at least the User Administrator role.
Fetch Event	Delegated Mail.ReadWrite Mail.Read offline_access	N/A	List messages - Microsoft Graph v1.0 Get attachment - Microsoft Graph v1.0
	Application Mail.ReadWrite Mail.Read
Fetch Related Events	Delegated Mail.ReadWrite Mail.Read offline_access	N/A	Get message - Microsoft Graph v1.0 Get attachment - Microsoft Graph v1.0 List attachments - Microsoft Graph v1.0
	Application Mail.ReadWrite Mail.Read
Get Email Attachments	Delegated Mail.ReadBasic Mail.Read Mail.ReadWrite offline_access	N/A	Get attachment - Microsoft Graph v1.0
	Application Mail.Read Mail.ReadWrite
Get Email EMLs	Delegated Mail.ReadBasic Mail.Read Mail.ReadWrite offline_access	N/A	Get message - Microsoft Graph v1.0
	Application Mail.Read Mail.ReadWrite
Get Email Messages	Delegated Mail.ReadBasic Mail.Read Mail.ReadWrite offline_access	The Office 365 integration does not include the capability to access a shared mailbox or send messages as a different user. If users need to retrieve messages on behalf of another user, application permissions are required. With delegated permissions, it is only possible to access messages of the authenticated user calling the Office 365 API.	Get message - Microsoft Graph v1.0
	Application Mail.ReadBasic.All Mail.Read Mail.ReadWrite
List Mail Folders	Delegated Mail.ReadBasic Mail.ReadWrite Mail.Read offline_access	N/A	List mailFolders - Microsoft Graph v1.0 List childFolders - Microsoft Graph v1.0
	Application Mail.ReadBasic.All Mail.ReadWrite Mail.Read
List Message Rules	Delegated MailboxSettings.Read offline_access	N/A	List rules - Microsoft Graph v1.0
	Application MailboxSettings.Read
Move Email Messages	Delegated Mail.ReadWrite offline_access	N/A	message: move - Microsoft Graph v1.0
	Application Mail.ReadWrite
Remove Licenses	Delegated User.ReadWrite.All Directory.ReadWrite.All offline_access	Delegated The calling user needs one of the following Microsoft Entra roles: Directory Writers License Administrator User Administrator Global Administrator	Get a user - Microsoft Graph v1.0 user: assignLicense - Microsoft Graph v1.0
	Application User.ReadWrite.All Directory.ReadWrite.All	N/A
Reply All	Delegated Mail.Send, offline_access	N/A	message: replyAll - Microsoft Graph v1.0
	Application Mail.Send
Reply Mail	Delegated Mail.Send, offline_access	N/A	message: reply - Microsoft Graph v1.0
	Application Mail.Send
Report Emails	Delegated User.Read ThreatAssessment.ReadWrite.All offline_access	N/A	Get a user - Microsoft Graph v1.0 Create threatAssessmentRequest - Microsoft Graph v1.0
	Application Not Supported.
Search and Move Email Messages	Delegated Mail.ReadBasic Mail.ReadWrite offline_access If the Email Address parameter is left empty and the connection Grand Type is Authorization Code, users will need the following permissions to run this command: Mail.ReadBasic Mail.Read Mail.ReadWrite	N/A	List messages - Microsoft Graph v1.0 message: move - Microsoft Graph v1.0 Get message - Microsoft Graph v1.0
	Application Mail.ReadBasic.All Mail.ReadWrite
Send Mail	Delegated Mail.ReadWrite Mail.Send offline_access	The Office 365 integration does not include the capability to access a shared mailbox or send messages as a different user. If users need to retrieve messages on behalf of another user, application permissions are required. With delegated permissions, it is only possible to access messages of the authenticated user calling the Office 365 API.	Create message - Microsoft Graph v1.0 attachment: createUploadSession - Microsoft Graph v1.0 message: send - Microsoft Graph v1.0 user: sendMail - Microsoft Graph v1.0
	Application Mail.ReadWrite Mail.Send
Setup Auto Reply	Delegated MailboxSettings.ReadWrite offline_access	To configure an automatic reply message on behalf of another user, the integration connection must be authenticated using the Client_Credentials method, with the required Application permissions.	Update user mailbox settings - Microsoft Graph v1.0
	Application MailboxSettings.ReadWrite
Test Connection	Delegated permissions require the offline_access scope. Once the token is successfully generated, the connection will pass successfully.

READER NOTE

For the Report Emails command:

The permission type must be Delegated (work or school account) on the Azure Portal.
The grant type must be Authorization Code in D3 SOAR.

Privileged Role Permissions Matrix

In the following table, the columns list the roles that can perform sensitive actions. The rows list the roles for which the sensitive action can be performed upon.

The following table is for roles assigned at the scope of a tenant. For roles assigned at the scope of an administrative unit, further restrictions apply.

Role that sensitive action can be performed upon	Auth Admin	User Admin	Privileged Auth Admin	Global Admin
Auth Admin	✅		✅	✅
Directory Readers	✅	✅	✅	✅
Global Admin			✅	✅
Groups Admin		✅	✅	✅
Guest Inviter	✅	✅	✅	✅
Helpdesk Admin		✅	✅	✅
Message Center Reader	✅	✅	✅	✅
Password Admin	✅	✅	✅	✅
Privileged Auth Admin			✅	✅
Privileged Role Admin			✅	✅
Reports Reader	✅	✅	✅	✅
User (no admin role)	✅	✅	✅	✅
User (no admin role, but member or owner of a role-assignable group)			✅	✅
User Admin		✅	✅	✅
Usage Summary Reports Reader	✅	✅	✅	✅
All custom roles	✅	✅	✅	✅

Configuring Office 365 to Work with D3 SOAR

Grant Type: Client Credentials

Log in to the Azure Portal.
Navigate to the search bar at top and enter "App registrations", then select the matching result.
Users may also use an existing app.
Click + New registration at the top left corner to create a new App.
Register the app.
1. Enter an App name.
2. Choose the first option as the Supported account type if the intended usage is internal within the user’s own organization.
  For more information, click the Help me choose… link.
3. Click the Register button.
Copy the Directory (tenant) ID from the Overview page of the newly created app.
Refer to step 3i sub-step 2 of Default Connection Parameters in Configuring D3 SOAR to Work with Office 365.
Copy the Application (client) ID.
Refer to step 3i sub-step 4 of Default Connection Parameters in Configuring D3 SOAR to Work with Office 365.
Obtain the client secret Value.
1. Select the Add a certificate or secret link.
2. Click the + New client secret button.
3. Click the Add button.
4. Copy the Value. Refer to step 3i sub-step 5 of Default Connection Parameters in Configuring D3 SOAR to Work with Office 365.

Grant Type: Authorization Code

Log in to the Azure Portal.
Navigate to the search bar at top and enter "App registrations", then select the matching result.
Users may also use an existing app.
Click + New registration at the top left corner to create a new App.
Register the app.
1. Enter an App name.
2. Choose the first option as the Supported account type if the intended usage is internal within the user’s own organization.
  For more information, click the Help me choose… link.
3. Select Web from dropdown.
4. Paste the Callback URL obtained from vSOC connection form into the URI field in the Redirect URI (optional) section.
  Refer to step 3i sub-step 2 of Grant Type: Authorization Code in Configuring D3 SOAR to Work with Office 365.
5. Click Register.
For existing apps, users can add a redirect URI in the following steps:
1. Navigate to the desired app.
2. Select the Authentication tab.
3. Click + Add Platform.
4. Select the Web card.
5. Paste the Callback URI from vSOC.
6. Click the Configure button.
Refer to steps 5 through 7 in Grant Type: Client Credentials to obtain the Tenant ID, Client ID, and Client Secret.

Configuring the API Permissions

Users must configure API permissions before using the integration’s commands. The required permissions vary based on the grant type used for the connection and the specific commands the users intend to use.

To begin configuring API permissions:

Select the API permissions tab.
Click the + Add a permission button.
Click the Microsoft Graph tile.

Grant Type: Client Credentials

NOTE

The Fetch Event command will be used to demonstrate how to set API permissions for the Client Credentials grant type.

Select the Application permissions tile.
Add the Mail.Read and Mail.ReadWrite permissions according to the Permission Requirements table.
Click the Add permissions button.

Grant Type: Authorization Code

NOTE

The Send Email command will be used to demonstrate how to set API permissions for the Authorization grant type.

Select the Delegated permissions tile.
Add the Mail.ReadWrite and Mail.Send permissions according to the Permission Requirements table.
Click the Add permissions button.

READER NOTE

Some permissions require admin consent. An administrator can click Grant admin consent for ***** to grant admin consent. Non-administrators must contact an admin to perform this action.

Successfully admin-consent-granted permissions will appear with a green checkmark under the Status column.

Configuring D3 SOAR to Work with Office 365

Log in to D3 SOAR.
Find the Office 365 integration.
1. Navigate to Configuration on the top header menu.
2. Click on the Integration icon on the left sidebar.
3. Type Office 365 in the search box to find the integration, then click it to select it.
4. Click + Connection, on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to Office 365.
1. Connection Name: The desired name for the connection.
2. Site: Specifies the site to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all sites defined as internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.
3. Recipient site for events from connections Shared to Internal Sites: This field is displayed when Share to Internal Sites is selected for the Site field, allowing selection of the internal site for deploying the integration connection.
4. Agent Name (Optional): Specifies the proxy agent required to build the connection. Use the dropdown menu to select the proxy agent from a list of previously configured proxy agents.
5. Description (Optional): Add a description for the connection.
6. Tenant (Optional): When configuring the connection from a master tenant site, users have the option to choose the specific tenant sites to share the connection with. Once this setting is enabled, users can filter and select the desired tenant sites from the dropdowns to share the connection.
7. Configure User Permissions: Defines which users have access to the connection.
8. Active: Check the checkbox to ensure the connection is available for use.
9. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
  This screenshot shows the connection form configured with the Grant Type set to Client Credentials.
  Default Connection Parameters
  The following connection parameters are present regardless of the selected Grant Type.
  1. Select the Microsoft 365 Environment. By default, the Commercial & GCC Environment option is selected.
  2. Copy the Tenant ID from the Office 365 platform. Refer to step 5 in Grant Type: Client Credentials of Configuring Office 365 to Work with D3 SOAR for more details.
  3. Select the Grant Type. Available options are Client Credentials and Authorization Code. Authorization Code is the recommended option for this integration. The selected Grant Type determines which connection parameters are required.
  4. Copy the Client ID from the Office 365 platform. Refer to step 6 in Grant Type: Client Credentials of Configuring Office 365 to Work with D3 SOAR for more details.
  5. Copy the Client Secret from the Office 365 platform. Refer to step 7 in Grant Type: Client Credentials of Configuring Office 365 to Work with D3 SOAR for more details.
  6. The default API Version is v1.0. Use this value when executing commands.
  Grant Type: Client Credentials
  When Client Credentials is selected as the Grant Type, only the default connection parameters—Tenant ID, Client ID, Client Secret, and API Version—are required.
  Grant Type: Authorization Code
  When Authorization Code is selected as the Grant Type, additional parameters must be filled:
  1. Enter the Scopes to be granted for this connection. The default value is offline_access https://graph.microsoft.com/mail.ReadWrite https://graph.microsoft.com/mail.Send. Adjust the scopes according to the intended use case. Refer to the Reader Note for further information.
  2. Copy the Callback URL and paste it into the Redirect URI field in Office 365. Refer to step 4d in Grant Type: Authorization Code of Configuring Office 365 to Work with D3 SOAR.
  3. Click the Get Authorization button. Follow the prompts displayed in any subsequent pop-up windows.
  4. Click the Get Refresh Token button. The Authorization Code and Refresh Token will be generated automatically.
10. Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Refer to the password vault connection guide if needed.
11. Connection Health Check: Periodically checks the connection status by scheduling the Test Connection command at the specified interval (in minutes). Available only for active connections, this feature also allows configuring email notifications for failed attempts.
Test the connection.
1. Click on the Test Connection button to verify credentials and connectivity. A success alert displays Passed with a green checkmark. If the connection fails, review the parameters and retry.
2. Click OK to close the alert window.
3. Click + Add to create and add the configured connection.

READER NOTE

The following are the minimum required scopes for each command when using the Authorization Code grant type. Each scope value is space-delimited, and the offline_access scope is required for all commands.
For example, the minimum scope value required to use the Fetch Event command is: offline_access https://graph.microsoft.com/mail.ReadBasic https://graph.microsoft.com/mail.Read

Delete Email Message & Remove Office 365 Email (https://graph.microsoft.com/mail.ReadWrite)
Delete User Accounts (https://graph.microsoft.com/Directory.AccessAsUser.All)
Fetch Event (https://graph.microsoft.com/mail.ReadBasic https://graph.microsoft.com/mail.Read)
Fetch Related Events (https://graph.microsoft.com/mail.ReadBasic https://graph.microsoft.com/mail.Read)
Get Email Attachments (https://graph.microsoft.com/mail.ReadBasic https://graph.microsoft.com/mail.Read)
Get Email EMLs & Get EML Attachment (https://graph.microsoft.com/mail.ReadBasic https://graph.microsoft.com/mail.Read)
Get Email Messages & Search Office 365 Email (https://graph.microsoft.com/mail.ReadBasic https://graph.microsoft.com/mail.Read)
List Mail Folders (https://graph.microsoft.com/mail.ReadBasic https://graph.microsoft.com/mail.Read)
List Message Rules (https://graph.microsoft.com/MailboxSettings.Read)
Move Email Messages & Move Email to Junk Box (https://graph.microsoft.com/mail.ReadWrite)
Remove Licenses (https://graph.microsoft.com/User.ReadWrite.All https://graph.microsoft.com/Directory.ReadWrite.All)
Reply All (https://graph.microsoft.com/Mail.Send)
Reply Mail (https://graph.microsoft.com/Mail.Send)
Report Emails (https://graph.microsoft.com/threatAssessment.ReadWrite.All https://graph.microsoft.com/directory.Read.All https://graph.microsoft.com/directory.ReadWrite.All https://graph.microsoft.com/directory.AccessAsUser.All https://graph.microsoft.com/user.Read.All https://graph.microsoft.com/user.ReadWrite.All https://graph.microsoft.com/user.Read https://graph.microsoft.com/user.ReadWrite https://graph.microsoft.com/user.ReadBasic.All)
Search and Move Email Messages (https://graph.microsoft.com/mail.ReadWrite)
Send Mail (https://graph.microsoft.com/mail.Send https://graph.microsoft.com/mail.ReadWrite)

Commands

Office 365 includes the following executable commands for users to set up schedules or create playbook workflows. With the Test Command, users can execute these commands independently for playbook troubleshooting.

Integration API Note

For more information about the Office 365 API, please refer to the Office 365 API reference.

READER NOTE

Certain permissions are required for each command. Please refer to the Permission Requirements and Configuring Office 365 to Work with D3 SOAR for details.

Integration Designed Query

Some commands (Fetch Event and Fetch Related Events) require structured input arguments in Office 365 designed query formats.

Users should take either query parameter ($filter or $search) for the search criteria depending on the use case.

$filter: Use the $filter query parameter to retrieve just a subset of a collection.
$search: $search uses Keyword Query Language (KQL). Microsoft Graph supports the $search query parameter to restrict the results of a request to match a search criterion. A $search request returns up to 1000 results.

Note for Time-related parameters

The input format of time-related parameters may vary based on user account settings, which may cause the sample data in commands to differ from what is displayed. To adjust the time format, follow these steps:

Navigate to Configuration > Application Settings. Select Date/Time Format.
Choose the desired date and time format.

The selected time format will now be visible when configuring Date/Time command input parameters.

Delete Email Message

Deletes the specified email messages.

READER NOTE

The authorized access code is user account–based and cannot access data from other user accounts. If the connection uses the Authorization Code grant type, the Email Addresses or User IDs parameter will default to the logged-in user’s information and may be left blank.
If the connection grant type is Client Credentials, the Email Addresses or User IDs parameter must be specified.
The input Email Addresses or user IDs can be searched by using the toRecipients key in the Fetch Event raw data JSON object.
Message IDs is a required parameter to run this command.
- Run the Fetch Event command to obtain the Message IDs. Message IDs can be found in the raw data at the path $value[*].id.
- Each input message ID must correspond to the appropriate email address or user ID. This association can be confirmed in the raw data response, where the id or internetMessageId aligns with the value in toRecipients.

Input

Input Parameter

Required/Optional

Description

Example

Email Addresses or User IDs

Optional

The email addresses or user IDs to run the command.

This parameter can be left blank if the grant type for the connection is Authorization Code. Only the logged in user's email address will be used for the query.

To access any user mailbox with this command, users will need to select the Client Credential grant type in the connection configuration.

JSON

[
  "test@example.onmicrosoft.com",
  "test1@example.onmicrosoft.com"
]

Message IDs

Required

The IDs of the messages to delete. Message IDs can be obtained using the Fetch Event command.

Each message ID must correspond to the user ID or principal name at the same index in the array. For example, if the message ID array contains message1, message2 and the user array contains user1, user2, then message1 is associated with user1, message2 with user2, and so forth.

JSON

["*****"]

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Delete Email Message failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Office 365 portal. Refer to the HTTP Status Code Registry for details.	Status Code: 404.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Resource could not be discovered.

Error Sample Data

Delete Email Message failed.

Status Code: 404.

Message: Resource could not be discovered.

Delete User Accounts

Deletes the specified user accounts. Upon deletion, user resources are moved to a temporary container and can be restored within 30 days. After the period passes, they are permanently deleted.

READER NOTE

To delete users with privileged administrator roles, the user initiating the request must hold one of these Microsoft Entra roles: User Administrator, Privileged Authentication Administrator, or Global Administrator. In scenarios where delegation is involved, the application requires the Directory.AccessAsUser.All delegated permission. Additionally, the user making the request must possess a higher level of administrative privilege as detailed in the "Who can perform sensitive actions" section of the Working with users in Microsoft Graph document.
In situations where the application operates independently (app-only scenarios), merely having the User.ReadWrite.All application permission is insufficient to delete users with privileged administrative roles. The application must be granted a higher administrative role, as outlined in the "Who can perform sensitive actions" section of the Working with users in Microsoft Graph document.

Input

Input Parameter	Required/Optional	Description	Example
User IDs Or User Principal Names	Required	The IDs or Principal Names of the users to be deleted.	JSON `[ "test@example.com" ]`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Delete User Accounts failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Office 365 portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Insufficient privileges to complete the operation.

Error Sample Data

Delete User Accounts failed.

Status Code: 403.

Message: Insufficient privileges to complete the operation.

Fetch Event

Returns emails as events from the platform.

READER NOTE

The Search parameter uses Office 365's $search query parameter, while Filter is using the $filter query parameter.
- If the Filter parameter is defined, leave the Search parameter blank. Otherwise, an error of "Filter and Search cannot be used at the same time" will be returned.
- $filter basic syntax is <Property Name> <operator> <Expression>
  - Refer to Syntax for using the filter OData query parameter for further information.
- $search parameter is using KQL language, the basic syntax is <Property Name>:<Expression>
  - Refer to Use the $search query parameter for available property names.
  - Users may only specify a value without a specific property name. In such cases, the search will apply to the default properties: from, subject, and body.
The authorized access code is user account–based and cannot access data from other user accounts. If the connection uses the Authorization Code grant type, the Email Address parameter will default to the logged-in user’s information and may be left blank.
If the connection grant type is Client Credentials, the Email Address parameter must be specified.
The input Email Addresses or user IDs can be searched by using the toRecipients key in the Fetch Event raw data JSON object.
Mail Folder is a required parameter to run this command.
- Both Mail Folder IDs and Mail Folder names are accepted.
- Run the List Mail Folders command to obtain the Mail Folder. Mail folders can be found in the raw data at the paths $.value[*].id (Mail Folder IDs) and $.value[*].displayName (Mail Folder Names).

Input

Input Parameter	Required/Optional	Description	Example
Email Address	Optional	The email address from which to fetch events. This parameter can be left blank if the grant type for the connection is Authorization Code. Only the logged in user's email address will be used for the query. To access any user mailbox with this command, users will need to select the Client Credential grant type in the connection configuration.	test@example.com
Mail Folders	Required	The mail folders from which to fetch emails. Mail folders can be obtained using the List Mail Folders command. Use the folder name for well-known folders (e.g., archive); otherwise, provide the folder ID. Refer to mailFolder resource type - Microsoft Graph v1.0 for supported well-known folder names.	JSON `[ "Inbox" ]`
Start Time	Required	The start time of the time range to fetch events in UTC time.	2022-01-09 00:00
End Time	Required	The end time of the time range to fetch events in UTC time format.	2023-01-06 00:00
Number of Event(s) Fetched	Optional	The maximum number of emails per folder returned in a single event fetch. Valid values range from 1 to 1000. By default, the value is 10. When multiple folders are specified in the Mail Folders parameter, the total number of returned emails is the sum of results from each folder. For example, if the value is set to 5 and 3 folders are specified, up to 15 email events will be returned. A higher number of emails, particularly those with attachments, may increase command execution time. Use a moderate value to reduce the risk of timeouts and limit raw data size.	10
Filter	Optional	The queries to filter results. Filter uses the $filter query parameter. For the $filter syntax, see Syntax for using the $filter OData query parameter.	hasAttachments eq true and contains(subject, 'test')
Search Condition	Optional	The search condition expression. Leave this field empty if the Filter parameter is defined. Search uses the $search query parameter. $search uses Keyword Query Language (KQL) syntax. For the KQL syntax, see Keyword Query Language (KQL) syntax reference \| Microsoft Learn. For the available Property Names, see Use the $search query parameter in Microsoft Graph.	body:test or subject:test
Tolerance Scope	Optional	The tolerance scope in minutes of the query to get emails between start and end time to avoid the loss of emails. The email will be fetched between {Start Time - Tolerance Scope, End Time}.	10

Output

To view the sample output data for all commands, refer to this article.

Fetch Event Field Mapping

Fetch Event commands require event field mapping. Field mapping plays a key role for data normalization within the event pipeline. Field mapping converts the original data fields from the different providers to standardized D3 fields as defined by the D3 Model. Refer to Event and Incident Intake Field Mapping for details.

To add a custom field, click on the + Add Field button. Users can also remove built-in field mappings by clicking x. Note that two underscore characters will automatically prefix the defined Field Name as the System Name for a custom field mapping. Additionally, if an input Field Name contains any spaces, they will automatically be replaced with underscores for the corresponding System Name.

As a system integration, the Office 365 integration has some pre-configured field mappings for default field mapping.

Default Event Source
The Default Event Source is the default set of field mappings that are applied when this fetch event command is executed. For out-of-the-box integrations, users will find a set of field mappings provided by the system. Default event source provides field mappings for common fields from the fetched data. The default event source has a "Main Event JSON Path" (i.e. $.value) that is used to extract a batch of events from the response raw data. View the "Main Event JSON Path" by clicking on the Edit Main JSON Path button.
- Main Event JSON Path: $.value
  The Main Event JSON Path determines the root path where the system starts parsing raw response data into D3 event data. The JSON path begins with $, representing the root element. The path is formed by appending a sequence of child elements to $, each separated by a dot (.). Square brackets with nested quotation marks ([‘...']) should be used to separate child elements in JSON arrays.
  For example, the root node of a JSON Path is value. The child node denoting the Unique Event Key field would be id. Putting it together, the JSON Path expression to extract the Unique Event Key is $.value.id.

The pre-configured field mappings are detailed below:

Field Name	Source Field
Attachment Name	.attachments.name
CcRecipients	.ccRecipients
Description	.subject
Email subject	.subject
Event Type*	N/A. See the Reader Note.
File Content	.attachments[*].contentBytes
Filename	.attachments[*].name
Importance	.importance
Internal message ID	.internetMessageId
Message Authentication Results	.internetMessageHeaders[?(@.name==Authentication-Results)].value
Message body	.body.content
Message ID	.id
Original Email Body	.originalEmail[*].detail.item.body.content
Original Email CcRecipients	.originalEmail[*].detail.item.ccRecipients
Original Email Subject	.originalEmail[*].detail.item.subject
Original EML Item Attachment D3 Files	..originalEmail[].detail.item.attachments[]..D3File
Original File Content	.originalEmail[].detail.item.attachments[].contentBytes
Original File Name	.originalEmail[].detail.item.attachments[].name
Original Message File Attachment D3 File ID	..originalMessageFile[].attachment[].fileId
Original Message File Attachment Hash MD5	..originalMessageFile[].attachment[].md5
Original Message File Attachment Hash Sha1	..originalMessageFile[].attachment[].sha1
Original Message File Attachment Name	..originalMessageFile[].attachments[].filename
Original Message File Attachment Sha256	..originalMessageFile[].attachment[].sha256
Original Message File Body	..originalMessageFile[*].body[?(@.content_type=='text/html'
Original Message File CcRecipients	..originalMessageFile[*].header.cc
Original Message File From	..originalMessageFile[*].header.from
Original Message File Received Domains	..originalMessageFile[*].header.received_domain
Original Message File Received IPs	..originalMessageFile[*].header.received_ip
Original Message File Sent DateTime	..originalMessageFile[*].header.date
Original Message File Subject	..originalMessageFile[*].header.subject
Original Message File ToRecipients	..originalMessageFile[*].header.to
Original recipient	.originalEmail[].detail.item.toRecipients[].emailAddress.address
Original sender	.originalEmail[*].detail.item.sender.emailAddress.address
Recipient	.toRecipients[*].emailAddress.address
Sender	.sender.emailAddress.address
Unique Event Key	.id

READER NOTE

*Email Alerts

In D3 SOAR, the events from Office 365 will be predefined with Email Alerts as the Event Type.

Please note that the source type for Event Type is defined as Placeholder. Email Alerts is a default mapping value provided by D3.

See Event and Incident Intake Field Mapping/Source for more details on event field mapping field types.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Fetch Event failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Office 365 portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Get Token Fail.

Error Sample Data

Fetch Event failed.

Status Code: 403.

Message: Get Token Fail.

Fetch Related Events

Returns related emails as events based on specified parameters.

READER NOTE

The Search parameter uses Office 365's $search query parameter, while Filter is using the $filter query parameter.
- If the Filter parameter is defined, leave the Search parameter blank. Otherwise, an error of "Filter and Search cannot be used at the same time" will be returned.
- $filter basic syntax is <Property Name> <operator> <Expression>
  - Refer to Syntax for using the filter OData query parameter for further information.
- $search parameter is using KQL language, the basic syntax is <Property Name>:<Expression>
  - Refer to Use the $search query parameter for available property names.
  - Users may only specify a value without a specific property name. In such cases, the search will apply to the default properties: from, subject, and body.
The authorized access code is user account–based and cannot access data from other user accounts. If the connection uses the Authorization Code grant type, the Email Address parameter will default to the logged-in user’s information and may be left blank.
If the connection grant type is Client Credentials, the Email Address parameter must be specified.
Email Address is a required parameter to run this command.
- Run the Fetch Event command to obtain the Email Address. Email Addresses can be found in the raw data at the paths $.value[*].id.
Mail Folder is a required parameter to run this command.
- Both Mail Folder IDs and Mail Folder names are accepted.
- Run the List Mail Folders command to obtain the Mail Folder. Mail folders can be found in the raw data at the paths $.value[*].id (Mail Folder IDs) and $.value[*].displayName (Mail Folder Names).

Input

Input Parameter	Required/Optional	Description	Example
Email Address	Optional	The email address from which to fetch related events. This parameter can be left blank if the grant type for the connection is Authorization Code. Only the logged in user's email address will be used for the query. To access any user mailbox with this command, users will need to select the Client Credential grant type in the connection configuration.	test@example.com
Mail Folder	Required	The mail folders from which to fetch emails. Mail folders can be obtained using the List Mail Folders command. Use the folder name for well-known folders (e.g., archive); otherwise, provide the folder ID. Refer to mailFolder resource type - Microsoft Graph v1.0 for supported well-known folder names.	inbox
The Hours Before	Required	The number of hours before the current time.	11
Top Recent Event Number	Optional	The maximum number of the most recent events to fetch. Valid values range between 1 and 1000. By default, the value is 10.	1
Filter	Optional	The queries to filter results. Filter uses the $filter query parameter. For the $filter syntax, see Syntax for using the $filter OData query parameter.	createdDateTime gt 2020-04-21
Search	Optional	The search condition expression. Leave this field empty if the Filter parameter is defined. Search uses the $search query parameter. $search uses Keyword Query Language (KQL) syntax. For the KQL syntax, see Keyword Query Language (KQL) syntax reference \| Microsoft Learn. For the available Property Names, see Use the $search query parameter in Microsoft Graph.	body:excitement

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Fetch Related Events failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Office 365 portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: ErrorInvalidUser.

Error Sample Data

Fetch Related Events failed.

Status Code: 400.

Message: ErrorInvalidUser.

Get Email Attachments

Retrieves email attachment files according to the specified criteria and saves them to D3's database. Corresponding File IDs will be returned, and they can be used as input values for other commands (e.g. Detonate Files from the VirusTotal v3 integration or Create Ticket from the ServiceNow integration) for further analyses or actions.

READER NOTE

The authorized access code is user account–based and cannot access data from other user accounts. If the connection uses the Authorization Code grant type, the Email Addresses or User IDs parameter will default to the logged-in user’s information and may be left blank.
If the connection grant type is Client Credentials, the Email Addresses or User IDs parameter must be specified.
The input Email Addresses or user IDs can be searched by using the toRecipients key in the Fetch Event raw data JSON object.
Message IDs is a required parameter to run this command.
- Run the Fetch Event command to obtain the Message IDs. Message IDs can be found in the raw data at the path $value[*].id.
- Each input message ID must correspond to the appropriate email address or user ID. This association can be confirmed in the raw data response, where the id or internetMessageId aligns with the value in toRecipients.
If users input an email with no attachments, the command will run successfully with no results returned.

Input

Input Parameter

Required/Optional

Description

Example

Email Addresses or User IDs

Optional

The email addresses or user IDs from which to retrieve email attachments.

This parameter can be left blank if the grant type for the connection is Authorization Code. Only the logged in user's email address will be used for the query.

To access any user mailbox with this command, users will need to select the Client Credential grant type in the connection configuration.

JSON

[
  "test@example.com",
  "test1@example.com"
]

Message IDs

Required

The IDs of the messages to retrieve. Message IDs can be obtained using the Fetch Event command.

Each message ID must correspond to the user ID or principal name at the same index in the array. For example, if the message ID array contains message1, message2 and the user array contains user1, user2, then message1 is associated with user1, message2 with user2, and so forth.

JSON

[ "*****" ]

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Email Attachments failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Office 365 portal. Refer to the HTTP Status Code Registry for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: NoPermissionsInAccessToken.

Error Sample Data

Get Email Attachments failed.

Status Code: 401.

Message: NoPermissionsInAccessToken.

Get Email EMLs

Retrieves emails in EML format according to the specified criteria and saves them to D3's database. EML files contain the contents of the email, including the subject, sender, recipients, date of the message, and any file attachments. Corresponding File IDs will be returned, which can be used for the Get File Content utility command.

READER NOTE

The authorized access code is user account–based and cannot access data from other user accounts. If the connection uses the Authorization Code grant type, the Email Addresses or User IDs parameter will default to the logged-in user’s information and may be left blank.
If the connection grant type is Client Credentials, the Email Addresses or User IDs parameter must be specified.
The input Email Addresses or user IDs can be searched by using the toRecipients key in the Fetch Event raw data JSON object.
Message IDs is a required parameter to run this command.
- Run the Fetch Event command to obtain the Message IDs. Message IDs can be found in the raw data at the path $value[*].id.
- Both Message ID ($value[*].id) and Internet Message ID ($value[*].internetMessageId) are accepted.
- Each input message ID must correspond to the appropriate email address or user ID. This association can be confirmed in the raw data response, where the id or internetMessageId aligns with the value in toRecipients.

Input

Input Parameter

Required/Optional

Description

Example

Email Addresses or User IDs

Optional

The email addresses or user IDs from which to retrieve emails in EML format.

This parameter can be left blank if the grant type for the connection is Authorization Code. Only the logged in user's email address will be used for the query.

To access any user mailbox with this command, users will need to select the Client Credential grant type in the connection configuration.

JSON

[
  "test@example.com",
  "test1@example.com"
]

Message IDs

Required

The IDs of the messages to retrieve. Message IDs can be obtained using the Fetch Event command.

Each message ID must correspond to the user ID or principal name at the same index in the array. For example, if the message ID array contains message1, message2 and the user array contains user1, user2, then message1 is associated with user1, message2 with user2, and so forth.

JSON

[ "*****" ]

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Email EMLs failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Office 365 portal. Refer to the HTTP Status Code Registry for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: NoPermissionsInAccessToken.

Error Sample Data

Get Email EMLs failed.

Status Code: 401.

Message: NoPermissionsInAccessToken.

Get Email Messages

Retrieves email message by the specified user and message IDs.

READER NOTE

The authorized access code is user account–based and cannot access data from other user accounts. If the connection uses the Authorization Code grant type, the Email Addresses or User IDs parameter will default to the logged-in user’s information and may be left blank.
If the connection grant type is Client Credentials, the Email Addresses or User IDs parameter must be specified.
The input Email Addresses or user IDs can be searched by using the toRecipients key in the Fetch Event raw data JSON object.
Message IDs is a required parameter to run this command.
- Run the Fetch Event command to obtain the Message IDs. Message IDs can be found in the raw data at the path $value[*].id.
- Both Message ID ($value[*].id) and Internet Message ID ($value[*].internetMessageId) are accepted.
- Each input message ID must correspond to the appropriate email address or user ID. This association can be confirmed in the raw data response, where the id or internetMessageId aligns with the value in toRecipients.

Input

Input Parameter

Required/Optional

Description

Example

Email Addresses or User IDs

Optional

The email addresses or user IDs from which to retrieve emails.

This parameter can be left blank if the grant type for the connection is Authorization Code. Only the logged in user's email address will be used for the query.

To access any user mailbox with this command, users will need to select the Client Credential grant type in the connection configuration.

JSON

[
  "test@example.com",
  "test1@example.com"
]

Message IDs

Required

The IDs of the messages to retrieve. Message IDs can be obtained using the Fetch Event command.

Each message ID must correspond to the user ID or principal name at the same index in the array. For example, if the message ID array contains message1, message2 and the user array contains user1, user2, then message1 is associated with user1, message2 with user2, and so forth.

JSON

[ "*****" ]

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Email Messages failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Office 365 portal. Refer to the HTTP Status Code Registry for details.	Status Code: 401.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: NoPermissionsInAccessToken.

Error Sample Data

Get Email Messages failed.

Status Code: 401.

Message: NoPermissionsInAccessToken.

List Mail Folders

Retrieves a list of mail folders.

READER NOTE

The authorized access code is user account–based and cannot access data from other user accounts. If the connection uses the Authorization Code grant type, the Email Addresses or User IDs parameter will default to the logged-in user’s information and may be left blank.
If the connection grant type is Client Credentials, the Email Addresses or User IDs parameter must be specified.
The input Email Addresses or user IDs can be searched by using the toRecipients key in the Fetch Event raw data JSON object.

Input

Input Parameter	Required/Optional	Description	Example
Email Addresses or User IDs	Optional	The email addresses or user IDs for which to list mail folders. This parameter can be left blank if the grant type for the connection is Authorization Code. Only the logged in user's email address will be used for the query. To access any user mailbox with this command, users will need to select the Client Credential grant type in the connection configuration.	JSON `[ "test@example.com", "test1@example.com" ]`
Include Hidden Folders	Optional	Whether to include hidden folders in the returned list. By default, the value is set to False.	False
Parent Folder ID	Optional	The parent folder of the folders to retrieve. By default, the parent folder is set to root (also known as "Top of Information Store"), which returns the top-level folders. If the parent folder is a well-known folder, the folder name can be used in place of a folder ID. Refer to mailFolder resource type - Microsoft Graph v1.0 for supported well-known folder names.	Inbox

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Mail Folders failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Office 365 portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: ResourceNotFound.

Error Sample Data

List Mail Folders failed.

Status Code: 400.

Message: ResourceNotFound.

List Message Rules

Retrieves all messageRule objects defined for the specified user's inbox.

READER NOTE

The authorized access code is user account–based and cannot access data from other user accounts. If the connection uses the Authorization Code grant type, the User Principal Name parameter will default to the logged-in user’s information and may be left blank.
If the connection grant type is Client Credentials, the User Principal Name parameter must be specified.

Input

Input Parameter

Required/Optional

Description

Example

User Principal Name

Optional

The email address for which to list message rules.

This parameter can be left blank if the grant type for the connection is Authorization Code. Only the logged in user's email address will be used for the query.

To access any user mailbox with this command, users will need to select the Client Credential grant type in the connection configuration.

test@example.com

Rule Name

Optional

Filters search result by the message rule name. By default, all message rules of the specified user will be returned.

forwarding

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	List Message Rules failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Office 365 portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: User Principal Name is required if the Grant Type of the Connector is "Client Credentials".

Error Sample Data

List Message Rules failed.

Status Code: 400.

Message: User Principal Name is required if the Grant Type of the Connector is "Client Credentials".

Move Email Messages

Moves the specified messages to the destination mail folder.

READER NOTE

The authorized access code is user account–based and cannot access data from other user accounts. If the connection uses the Authorization Code grant type, the Email Addresses or User IDs parameter will default to the logged-in user’s information and may be left blank.
If the connection grant type is Client Credentials, the Email Addresses or User IDs parameter must be specified.
The input Email Addresses or user IDs can be searched by using the toRecipients key in the Fetch Event raw data JSON object.
Message IDs is a required parameter to run this command.
- Run the Fetch Event command to obtain the Message IDs. Message IDs can be found in the raw data at the path $value[*].id.
- Both Message ID ($value[*].id) and Internet Message ID ($value[*].internetMessageId) are accepted.
- Each input message ID must correspond to the appropriate email address or user ID. This association can be confirmed in the raw data response, where the id or internetMessageId aligns with the value in toRecipients.
Destination Mail Folder is a required parameter to run this command.
- Both Mail Folder IDs and Mail Folder names are accepted.
- Run the List Mail Folders command to obtain the Destination Mail Folder. Destination Mail Folders can be found in the raw data at the paths $.value[*].id (Mail Folder IDs) and $.value[*].displayName (Mail Folder names).

Input

Input Parameter	Required/Optional	Description	Example
Email Addresses or User IDs	Optional	The email addresses or user IDs for which to move email messages. This parameter can be left blank if the grant type for the connection is Authorization Code. Only the logged in user's email address will be used for the query. To access any user mailbox with this command, users will need to select the Client Credential grant type in the connection configuration.	JSON `[ "test@example.com", "test1@example.com" ]`
Message IDs	Required	The IDs of the messages to move. Message IDs can be obtained using the Fetch Event command. Each message ID must correspond to the user ID or principal name at the same index in the array. For example, if the message ID array contains `message1`, `message2` and the user array contains `user1`, `user2`, then `message1` is associated with `user1`, `message2` with `user2`, and so forth.	JSON `[ "*****" ]`
Destination Mail Folder	Required	The name or ID of the destination mail folder where the messages should be moved. Destination Mail Folder can be obtained using the List Mail Folders command. Use the folder name for well-known folders (e.g., archive); otherwise, provide the folder ID. Refer to mailFolder resource type - Microsoft Graph v1.0 for supported well-known folder names.	archive

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Move Email Messages failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Office 365 portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Resource could not be discovered.

Error Sample Data

Move Email Messages failed.

Status Code: 400.

Message: Resource could not be discovered.

Remove Licenses

Remove all licenses from the specified users.

Input

Input Parameter	Required/Optional	Description	Example
User ID or Email Address	Required	The IDs or Principal Names of the users from whom to remove licenses.	JSON `[ "test@example.com" ]`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Remove Licenses failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Office 365 portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Insufficient privileges to complete the operation.

Error Sample Data

Remove Licenses failed.

Status Code: 403.

Message: Insufficient privileges to complete the operation.

Reply All

Reply to all recipients of a message.

READER NOTE

Message ID is a required parameter to run this command.

Run the Fetch Event command to obtain the Message ID. Message IDs can be found in the raw data at the path $.value[*].id.

File ID and File Source

It is not recommended to use the Test Command feature with the Reply All command as it is designed for dynamic input files in Playbooks, Incident Attachments, and Artifact Attachments. There is a simple workaround to test the command:

Navigate to Configuration on the top bar menu.
Click on Utility Commands on the left sidebar menu.
Use the search box to find and select the Create a File from input Text Array command.
Click on the Test tab.
Input the required information for the parameters.
Click on the Test Command button. A D3 File ID will appear in the output data after the file has been successfully created. The D3 File Source of the created file will be Playbook File.

Input

Input Parameter	Required/Optional	Description	Example
Sender Email	Optional	The email address from which the reply-all message is sent. This parameter can be left blank if the grant type for the connection is Authorization Code. Only the logged in user's email address will be used for the query. To access any user mailbox with this command, users will need to select the Client Credential grant type in the connection configuration.	test@example.com
Message ID	Required	The ID of the message to reply to all. Message ID can be obtained using the Fetch Event command.	*****
Subject	Optional	The subject line of the reply-all email message.	Reply Email Test
Content	Optional	The body content of the reply-all email message.	Test Email Message
File IDs	Optional	The IDs of files to attach to the reply-all email.	JSON `["*****"]`
File Source	Optional	The file source of the files to be attached. Available options are: Incident Attachment File: Manually uploaded file from Incident Playbook File: Output from another Task Artifact File: Ingested Artifact in an Event. By default, the value is set to Incident Attachment File.	Incident Attachment File

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Reply All failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Office 365 portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: The parameter 'Sender Email' is required when your connection uses the 'Client Credential' Grant Type.

Error Sample Data

Reply All failed.

Status Code: 400.

Message: The parameter 'Sender Email' is required when your connection uses the 'Client Credential' Grant Type.

Reply Mail

Reply to the sender of a message.

READER NOTE

Message ID is a required parameter to run this command.

Run the Fetch Event command to obtain the Message ID. Message IDs can be found in the raw data at the path $.value[*].id.

File ID and File Source

It is not recommended to use the Test Command feature with the Reply Mail command as it is designed for dynamic input files in Playbooks, Incident Attachments, and Artifact Attachments. There is a simple workaround to test the command:

Navigate to Configuration on the top bar menu.
Click on Utility Commands on the left sidebar menu.
Use the search box to find and select the Create a File from input Text Array command.
Click on the Test tab.
Input the required information for the parameters.
Click on the Test Command button. A D3 File ID will appear in the output data after the file has been successfully created. The D3 File Source of the created file will be Playbook File.

Input

Input Parameter	Required/Optional	Description	Example
Sender Email	Optional	The email address from which the reply message is sent. This parameter can be left blank if the grant type for the connection is Authorization Code. Only the logged in user's email address will be used for the query. To access any user mailbox with this command, users will need to select the Client Credential grant type in the connection configuration.	test@example.com
Message ID	Required	The ID of the message to which to reply. Message ID can be obtained using the Fetch Event command.	*****
Subject	Optional	The subject line of the reply email message.	Reply Email Test
Content	Optional	The body content of the reply email message.	Test Email Message
File IDs	Optional	The IDs of files to attach to the reply email.	JSON `["*****"]`
File Source	Optional	The file source of the files to be attached. Available options are: Incident Attachment File: Manually uploaded file from Incident Playbook File: Output from another Task Artifact File: Ingested Artifact in an Event. By default, the value is set to Incident Attachment File.	Incident Attachment File

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Reply Mail failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Office 365 portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: The parameter 'Sender Email' is required when your connection uses the 'Client Credential' Grant Type.

Error Sample Data

Reply Mail failed.

Status Code: 400.

Message: The parameter 'Sender Email' is required when your connection uses the 'Client Credential' Grant Type.

Report Emails

Reports emails as phishing or spam. This command is available only when using a connection with the Authorization Code grant type. The ThreatAssessment.ReadWrite.All permission scope must also be granted.

READER NOTE

The permission type must be Delegated (work or school account) when configuring permissions on the Office 365 platform.
The User ID or Email Address parameter must match the account used to configure the connection.
Message IDs is a required parameter to run this command.
- Run the Fetch Event command to obtain the Message IDs. Message IDs can be found in the raw data at the path $value[*].id.
- Both Message ID ($value[*].id) and Internet Message ID ($value[*].internetMessageId) are accepted.

Input

Input Parameter	Required/Optional	Description	Example
User ID or Email Address	Required	The user ID or email addresses from which to report emails. Emails can only be reported from the account of the logged-in user associated with the active connection.	test@example.com
Message IDs	Required	The IDs of the messages to report. Message IDs can be obtained using the Fetch Event command. Each message can only be reported once. Attempting to report the same message multiple times will result in an error.	JSON `["*****"]`
Category	Required	The category (i.e., phishing or spam) of the reported emails. Available options are: Phishing Spam By default, the value is set to Phishing.	Phishing

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Report Emails failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Office 365 portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Insufficient privileges to complete the operation.

Error Sample Data

Report Emails failed.

Status Code: 403.

Message: Insufficient privileges to complete the operation.

Search and Move Email Messages

Queries messages and moves the specified messages to another folder within the specified user's mailbox in Office 365.

READER NOTE

Destination Mail Folder is a required parameter to run this command.

Both Mail Folder IDs and Mail Folder names are accepted.
Run the List Mail Folders command to obtain the Destination Mail Folder. Destination Mail Folders can be found in the raw data at the paths $.value[*].id (Mail Folder IDs) and $.value[*].displayName (Mail Folder names).

Input

Input Parameter	Required/Optional	Description	Example
Email Address	Optional	The email address in which messages will be moved to another folder. This parameter can be left blank if the grant type for the connection is Authorization Code. Only the logged in user's email address will be used for the query. To access any user mailbox with this command, users will need to select the Client Credential grant type in the connection configuration.	sys*@d3*****.onmicrosoft.com
Email Subject	Optional	The email subject specified to search related emails.	Microsoft Entra ID Protection Weekly Digest
Sender Email Address	Optional	The sender email address specified to search related emails.	**********-noreply@microsoft.com
Destination Mail Folder	Required	The name or ID of the destination mail folder where the messages should be moved. Destination Mail Folder can be obtained using the List Mail Folders command. Use the folder name for well-known folders (e.g., archive); otherwise, provide the folder ID. Refer to mailFolder resource type - Microsoft Graph v1.0 for supported well-known folder names.	Archive

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Search And Move Email Messages failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Office 365 portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Insufficient privileges to complete the operation.

Error Sample Data

Search And Move Email Messages failed.

Status Code: 403.

Message: Insufficient privileges to complete the operation.

Send Mail

Sends an email with optional attachments.

READER NOTE

The authorized access code is user account–based and cannot access data from other user accounts. If the connection uses the Authorization Code grant type, the Email Addresses or User IDs parameter will default to the logged-in user’s information and may be left blank.
If the connection grant type is Client Credentials, the Email Addresses or User IDs parameter must be specified.
To assign values to the CC Recipients and BCC Recipients fields, set the Reply Mode parameter to the No Reply option.

File ID and File Source

It is not recommended to use the Test Command feature with the Send Mail command as it is designed for dynamic input files in Playbooks, Incident Attachments, and Artifact Attachments. There is a simple workaround to test the command:

Navigate to Configuration on the top bar menu.
Click on Utility Commands on the left sidebar menu.
Use the search box to find and select the Create a File from input Text Array command.
Click on the Test tab.
Input the required information for the parameters.
Click on the Test Command button. A D3 File ID will appear in the output data after the file has been successfully created. The D3 File Source of the created file will be Playbook File.

Input

Input Parameter	Required/Optional	Description	Example
Mailbox Address	Optional	The email address from which the email is sent. This parameter will be omitted if the grant type for the connection is Authorization Code. Only the logged in user's email address will be used for the query. To access any user mailbox with this command, users will need to select the Client Credential grant type in the connection configuration.	test@example.com
Subject	Required	The subject of the email.	Test Email
Content	Optional	The content of the email.	Test Email Message
To Recipients	Required	The main recipients of the email.	JSON `["test@example.com"]`
CC Recipients	Optional	The CC recipients of the email. If CC recipients are specified, the Reply Mode parameter must be set to No Reply.	JSON `["test@example.com"]`
BCC Recipients	Optional	The BCC recipients of the email. If the BCC recipients are specified, the Reply Mode parameter must be set to No Reply.	JSON `["test@example.com"]`
File IDs	Optional	The IDs of files to attach to the email.	JSON `["*****"]`
File Source	Optional	The file source of the files to be attached. Available options are: Incident Attachment File: Manually uploaded file from Incident Playbook File: Output from another Task Artifact File: Ingested Artifact in an Event. By default, the value is set to Incident Attachment File.	Incident Attachment File
Reply Mode	Optional	The reply mode of the email. Available options are: No Reply (Enable CC and BCC) Require Reply Require All Reply Require Approval Require All Approval First to Approve/Reject	Require Reply
Reply Due Time	Optional	The duration (in minutes) to wait for a reply.	10
Send As	Optional	The email address from which the message is sent. The From property may be modified if the Exchange administrator has granted sendAs rights for the mailbox to other users. These permissions can be configured via Mailbox Permissions in the Azure portal, the Exchange Admin Center, or by using the `Add-ADPermission` cmdlet in PowerShell. By default, the message will be sent from the mailbox owner's address.	johndoe@example.com
Reply To	Optional	The email addresses to use when replying. By default, the address from which the message was sent will be used for replies.	JSON `[ "janedoe@example.com", "seandoe@example.com" ]`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Send Mail failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Office 365 portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Insufficient privileges to complete the operation.

Error Sample Data

Send Mail failed.

Status Code: 403.

Message: Insufficient privileges to complete the operation.

Setup Auto Reply

Configures the auto reply settings for the specified accounts.

Input

Input Parameter	Required/Optional	Description	Example
User IDs Or User Principal Names	Required	The IDs or principal names of the users for whom to set up automatic replies.	JSON `[ "test@example.com" ]`
Status	Optional	The configuration status for automatic replies. Available values are: Disabled Always Enabled Scheduled. By default, the value is set to Always Enabled.	Scheduled
Scheduled Start Time	Optional	The date and time at which automatic replies begin (in UTC), if Status is set to Scheduled. By default, the existing scheduled start time is used.	2023-10-10 00:00
Scheduled End Time	Optional	The date and time at which automatic replies end (in UTC), if Status is set to Scheduled. By default, the existing scheduled end time is used.	2023-10-20 00:00
Internal Reply Message	Optional	The automatic reply sent to recipients internal to the signed-in user's organization, if Status is set to Always Enabled or Scheduled. By default, the existing reply message is used.	HTML `<html> <body> <p>I am currently out of office and will respond to your message upon my return.</p> </body> </html>`
External Reply Message	Optional	The automatic reply sent to the specified external audience, if Status is set to Always Enabled or Scheduled. By default, the existing reply message is used.	HTML `<html> <body> <p>Thank you for your message. I am currently unavailable and will get back to you as soon as possible.</p> </body> </html>`

Output

To view the sample output data for all commands, refer to this article.

Error Handling

If the Return Data is Partially Successful or Failed, an Error tab will appear in the Test Result window.

The error tab contains the details responded from D3 SOAR or third-party API calls, including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Setup Auto Reply failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Office 365 portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Insufficient privileges to complete the operation.

Error Sample Data

Setup Auto Reply failed.

Status Code: 403.

Message: Insufficient privileges to complete the operation.

Test Connection

Allows users to perform a health check on an integration connection. Users can schedule a periodic health check by selecting Connection Health Check when editing an integration connection.

Input

N/A

Output

Output Type

Description

Return Data Type

Return Data

Indicates one of the possible command execution states: Successful or Failed.

The Failed state can be triggered by any of the following errors:

A connection issue with the integration
The API returned an error message
No response from the API

More details about an error can be viewed in the Error tab.

String

Error Handling

If the Return Data is failed, an Error tab will appear in the Test Result window.

The error tab contains the responses from the third-party API calls including Failure Indicator, Status Code, and Message. This can help locate the root cause of a command failure.

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Test Connection failed. Failed to check the connector.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Office 365 portal. Refer to the HTTP Status Code Registry for details.	Status Code: 403.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Insufficient privileges to complete the operation.

Error Sample Data

Test Connection failed. Failed to check the connector.

Status Code: 403.

Message: Insufficient privileges to complete the operation.

Deprecated Commands

The following deprecated commands are only supported by existing connections configured by current clients. We recommend current users to contact the D3 SOAR support team and assess the migration of their playbook commands from deprecated ones to the corresponding new commands.

Deprecated Commands	Achieved by
Move Email to junk box	Move Email Messages
Remove Office 365 Email	Delete Email Message
Search Office 365 Email	Get Email Messages
Get EML Attachment	Get Email EMLs + Get Email Attachments

FAQ

Why do I see an error like this when clicking get authorization when building connections?

Answer: Check if the callback URL was input to Redirect URI in Office 365. Please refer to step 3h iv of Configuring D3 SOAR to Work with Office 365 for more information.