Office 365

LAST UPDATED: 05/10/2024

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, please follow this part to collect the required information below:

Reader Note

If you select Authorization Code as the Grant Type, then you can only access the signed-in user's mailbox. If you need to access any other user's email box in the organization, you shall select Client Credentials.

Parameter	Description	Example
Default
Tenant ID	The tenant ID to authenticate the API connection.	f621adba-**--**-63e76149feed
Grant Type	The grant type to authenticate the API connection. If you select Authorization Code, you will only be able to access the signed-in user's mailbox. If you need 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.	9c8a3dd6-**--**-0dc3fffd9f8a
Client Secret	The client secret to authenticate the API connection.	o14taJ.tNMWvTEaE~********_2~PX817~
Grant Type: Authorization Code
Client ID	The client ID to authenticate the API connection.	9c8a3dd6-**--**-0dc3fffd9f8a
Client Secret	The client secret to authenticate the API connection.	o14taJ.tNMWvTEaE~********_2~PX817~
Scope	The scope 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.	0.AxgAu******53ZgR0Yf5******01AevfCBfQgAA
Callback URL	The callback URL is used for OAuth2.0 with the grant type of authorization code. Add this URL to your app's Redirect URIs. In the Azure portal, navigate to Microsoft Entra ID Protection > App Registrations > Your App > Authentication.	https://v2019.d3securityonline.net/V127Cyber/VSOC/Auth2Callback.aspx
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.	0.AXgAuq0h9******5AbndzWVRlaOHQ******RumRwHL5Yg

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

If you are using Authorization Code as the Grant Type, corresponding Delegated Permissions are required to execute commands.
If you are 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	-	Delete message - Microsoft Graph v1.0
	Application Mail.ReadWrite
Delete User Accounts	Delegated User.ReadWrite.All offline_access (Optional): 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.ReadBasic Mail.Read offline_access	-	List messages - Microsoft Graph v1.0 Get attachment - Microsoft Graph v1.0
	Application Mail.ReadBasic.All Mail.Read
Fetch Related Events	Delegated Mail.ReadBasic Mail.Read offline_access	-	Get message - Microsoft Graph v1.0 Get attachment - Microsoft Graph v1.0 List attachments - Microsoft Graph v1.0
	Application Mail.ReadBasic.All Mail.Read
Get Email Attachments	Delegated Mail.Read offline_access	-	Get attachment - Microsoft Graph v1.0
	Application Mail.Read
Get Email EMLs	Delegated Mail.ReadBasic Mail.Read offline_access	-	Get message - Microsoft Graph v1.0
	Application Mail.ReadBasic.All Mail.Read
Get Email Messages	Delegated Mail.ReadBasic Mail.Read offline_access	The Office 365 integration does not include the capability to access a shared mailbox or send messages as a different user. If you 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
List Mail Folders	Delegated Mail.ReadBasic offline_access	-	List mailFolders - Microsoft Graph v1.0 List childFolders - Microsoft Graph v1.0
	Application Mail.ReadBasic.All
Move Email Messages	Delegated Mail.ReadWrite offline_access	-	message: move - Microsoft Graph v1.0
	Application Mail.ReadWrite
Remove Licenses	Delegated User.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	-
Report Emails	Delegated User.Read ThreatAssessment.ReadWrite.All offline_access	-	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 If the Email Address parameter inside the command is left empty and the connection Grand Type has been selected as Authorization Code, you will need the following permissions to run this command: Mail.ReadBasic, Mail.Read Mail.ReadWrite	-	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 Calendars.ReadWrit 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 you 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 Calendars.ReadWrit Mail.Send
Setup Auto Reply	Delegated MailboxSettings.ReadWrite offline_access	To configure an automatic reply message for a different user, the integration connection must be authenticated using the Client_Credentials method, with the required Application permissions enabled.	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.

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

Log in to the Azure Portal ( https://portal.azure.com/ ) with your username and password.
Navigate to the search bar at top and search "App registrations", then click App Registrations.
If you have already created Apps, you can use one of them and skip to step 6 to obtain the Client ID & Tenant ID.
If you do not have an App, click + New registration at the top left corner to create a new App.
Enter an App name. Choose the first option as your Supported account type if your target audience is internal within your organization. For a more detailed description of different options, you can click Help me choose…, then select Web from the Redirect URI dropdown list and paste the Callback URI you copied from the SOAR connection window into the URI field. Finally, click Register.
Note: To copy the Callback URI from SOAR Connection Window, please refer to step 3h iv of Configuring D3 SOAR to Work with Office 365.
1. You can also add a redirect URI later. Click Overview on the navigation column, then click Add a Redirect URI.
2. Click Add Platform, then select Web.
3. Input your Redirect URIs and click Configure.
In the App Overview tab, copy and save the Application(client) ID and Directory(tenant) ID for creating the SOAR connection.
Click Certificates & secrets on the left navigation column, then click + New client secret. Enter a description for the client secret, and select the client secret expiry period from the Expires dropdown menu. Please note that the client ID cannot access API resources if the client secret is expired. You MUST renew the client secret if you want to keep the client ID effective. Click Add at the bottom.
Copy and save the Secret Value for the SOAR connection. Please note that you will only be able to view this Secret Value once after its initial creation. Store it in a secure location.
Configure the API permissions. Click API permissions on the left navigation column, then click + Add a permission. Click Microsoft Graph under the Microsoft APIs tab.
Select Delegated Permissions if you want to use the OAuth2 Authentication Code method. If you want to use the OAuth2 Client Credentials method, select Application permissions. For the Report Emails command which will report an email as either spam or phishing, the permission must be the Delegated Permissions for the account.

Reader Note

For the command Report Email:

The permission type must be Delegated (work or school account) when choosing permissions on the Office 365 platform.
The grant type must be Authorization Code in D3 SOAR.

Navigate to the Mail section, and enable related mail permissions, then click Add permissions. Please note that if you only need to read one user's mailbox, you will only need to add the delegated permission (NOT application permission): Mail.Read. If you want to use the Client Credentials method, you will need to add the application permission: Mail.Read. It is recommended only to grant the required API permissions.

Reader Note

Please refer to the Permission Requirements with the different commands in D3 SOAR Office365 Integration.

Some permissions may need to be granted admin consent. Please check Grant admin consent for D3******** to grant the API permissions. If you do not have admin privileges, ask your admin to grant consent.
Click Grant admin consent for D3********, then click Yes.
You will see a green checkmark under status. The permission is now successfully granted.

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 + New 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 appears if you selected Share to Internal Sites for Site to let you select the internal site to deploy 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 your desired description for the connection.
6. Configure User Permissions: Defines which users have access to the connection.
7. Active: Check the tick box to ensure the connection is available for use.
8. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
  1. Copy the Tenant ID from the Office 365 platform. (Refer to step 6 of Configuring Office 365 to Work with D3 SOAR for more details).
  2. Copy the Client ID from the Office 365 platform. (Refer to step 6 of Configuring Office 365 to Work with D3 SOAR for more details).
  3. Copy the Client Secret from the Office 365 platform (Refer to step 8 of Configuring Office 365 to Work with D3 SOAR for more details).
  4. There are two grant types: Client Credentials and Authorization Code. The Authorization Code grant type is recommended for this integration.
    Note: For the Report Email command:
    The permission type must be Delegated (work or school account) when choosing permissions on Office 365 platform.
    The grant type must be Authorization Code in D3 SOAR.
    1. If you choose the Client Credentials grant type: The default API Version is v1.0, please use the default value when running commands.
    2. If you choose the Authorization Code grant type:
      1. Copy the Callback URL, and paste it into Office 365 Redirect URI (Refer to step 5 of Configuring Office 365 to Work with D3 SOAR).
      2. Input the scopes you want to grant for this connection. The default value of the scope is offline_access https://graph.microsoft.com/mail.ReadWrite https://graph.microsoft.com/mail.Send. Please change it according to your use case.
      3. Click Get Authorization. Check your login account then accept the requested permission. You will be directed to the authorization page. Return to D3 SOAR.
      4. Click Get Refresh Token. The Authorization Code and Refresh Token will be auto-generated.
      5. The default API Version is v1.0, please use the default value when running commands.
9. Connection Health Check: Updates the connection status you have created. A connection health check is done by scheduling the Test Connection command of this integration. This can only be done when the connection is active.
  To set up a connection health check, check the Connection Health Check tickbox. You can customize the interval (minutes) for scheduling the health check. An email notification can be set up after a specified number of failed connection attempts.
10. Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Please refer to the password vault connection guide if needed.
Test the connection.
1. Click Test Connection to verify the account credentials and network connection. If the Test Connection Passed alert window appears, the test connection is successful. You will see Passed with a green checkmark appear beside the Test Connection button. If the test connection fails, please check your connection parameters and try again.
2. Click OK to close the alert window.
3. Click + Add to create and add the configured connection.

Commands

Office 365 includes the following executable commands for users to set up schedules or create playbook workflows. With the Test Command, you 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.

You 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 your account settings. As a result, the sample data provided in our commands is different from what you see. To set your preferred time format, follow these steps:

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

After that, you will be able to view your preferred time format when configuring the DateTime input parameters for commands.

Delete Email Message

Deletes the specified email messages.

Reader Note

The authorized access code is user account based which cannot read/write another user account data. If your selected grant type for the connection is Authorization Code, the input parameters Email Addresses or User IDs will use your login email addresses or user IDs as default, so you may leave it blank. See step 3h iv c of Configuring Office 365 to Work with D3 SOAR for more about login information.
If your connection grant type is Client Credentials, you must specify the Email Addresses or User IDs field.
Your input Email Addresses or user IDs can be searched by using the "toRecipients" key in the Fetch Event raw data JSON object.
The parameter Message IDs is required to run this command.
- You should already have your desired Message IDs on hand to run this command. If you don't, you may use the Fetch Event command with defined filters to retrieve the desired Event IDs. The Event IDs can be found in the raw data at the path $value[*].id.
- Please note that your input Message IDs must match to your Email Addresses or User IDs. You can find it in the raw data response. Your input "id" or "internetMessageId" must match the value of "toRecipients".

Input

Input Parameter

Required/Optional

Description

Example

Email Addresses or User IDs

Optional

The email addresses or user IDs to run the command.

Note: This parameter can be left blank if the grant type for the connection is Authorization Code. The logged in user's email address will be used for the query. You can only use the logged in user's account mailbox for the command.

To access any user mailbox with this command, you will need to select the Client Credential grant type during the initial configuration of the connection.

[ "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 should be associated with the corresponding user ID or principal name in the array. For instance, if the message ID array has message1, message2… etc., the user ID or principal name array would be user1, user2…etc. message1 would be associated with user1, and message2 with user2 and so on.

["AA*****AAA"]

Output

Raw Data

The primary response data from the API request.

D3 enriches the raw data from the original Office 365 API response by adding the messageID field to indicate your input message ID and adding actionResult field to indicate whether the messages have been deleted successfully.

SAMPLE DATA

JSON

[
    {
        "messageID": "AA*****AAA",
        "actionResult": "Deleted the message successfully"
    }
]

Return Data

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

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

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

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

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 you 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 account(s). When deleted, user resources are moved to a temporary container and can be restored within 30 days. After that time, 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.

[

"test@example.com"

]

Output

Raw Data

The primary response data from the API request.

D3 enriches the raw data from the original Office 365 API response by adding the messageID field to indicate your input message ID and adding actionResult field to indicate whether the messages have been deleted successfully.

SAMPLE DATA

JSON

{
    "results": [
        {
            "userIDorNames": "test@example.com",
            "actionResult": "Delete user successfully"
        }
    ]
}

Return Data

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

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

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

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

results	{'userIDorNames': 'test@example.com', 'actionResult': 'Delete user successfully'}

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 you 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 Condition parameter uses Office 365's $search query parameter, while the Filter parameter is using $filter query parameter.
- If you have defined the Filter parameter, leave the Search Condition parameter blank. Otherwise, the error message "Filter and Search cannot be used at the same time" will be returned.
- The basic syntax for the $filter query parameter is <Property Name> <Operator> <Expression>. For more information, see Use the $filter query parameter to filter a collection of objects - Microsoft Graph.
- The $search query parameter uses Keyword Query Language (KQL). The basic syntax is <Property Name>:<Expression>. For a list of available property names, see Use the $search query parameter in Microsoft Graph.
 - You may only specify a value without a specific property name. Then the default search properties are from, subject and body.
The authorized access code is user account based which cannot read/write another user account data. If your selected grant type for the connection is Authorization Code, the input parameters Email Address will use your login email address as default, so you may leave it blank. See step 3h iv c of Configuring D3 SOAR to Work with Office 365 for more about login information.
If your connection grant type is Client Credentials, you must specify the Email Address field.
Your input Email Addresses 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.
Run the List Mail Folders command to obtain Mail Folder. Please note both Mail Folder IDs and Mail Folder names are accepted.

Input

Input Parameter	Required/Optional	Description	Example
Email Address	Optional	The email address to fetch events from. Note: This parameter can be left blank if the grant type for the connection is Authorization Code. The logged in user's email address will be used for the query. You can only use the logged in user's account mailbox for the command. To access any user mailbox with this command, you will need to select the Client Credential grant type during the initial configuration of the connection.	test@example.com
Mail Folder	Required	The mail folder to fetch emails from. Both system folders and user-created folders can be used to define this parameter. Folder ID can be used to search for both types of folder, however only system default folders can be searched by folder name. The available default folder names are "archive", "clutter", "conflicts", "conversationhistory", "deleteditems", "drafts", "inbox", "junkemail", "localfailures", "msgfolderroot", "outbox", "recoverableitemsdeletions", "scheduled", "searchfolders", "sentitems", "serverfailures" and "syncissues". Note: Spaces cannot be used in folder names. For user-created folders, the value must be the Folder ID. Mail folders can be obtained using the List Mail Folders command.	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 returned within a single instance of event fetching. A valid value is between 1 and 1000. If not specified, the default value is 10.	10
Filter	Optional	The queries to filter results. Filter is using $filter query parameter. For the $filter syntax, see Syntax for using the $filter OData query parameter from Microsoft's documentation.	hasAttachments eq true and contains(subject, 'test')
Search Condition	Optional	The search condition expression. Leave this field empty if the Filter parameter is defined. Filter is using $search query parameter. $search is using 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

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
  "@odata.context": "https://*****.com/***",
  "value": [
      {
          "@odata.etag": "W/\"CQ*****by\"",
          "id": "***************************************",
          "createdDateTime": "2021-05-13T21:48:49Z",
          "lastModifiedDateTime": "2021-05-13T21:48:51Z",
          "changeKey": "CQ*****by",
          "categories": [],
          "receivedDateTime": "2021-05-13T21:48:50Z",
          "sentDateTime": "2021-05-13T21:46:50Z",
          "hasAttachments": true,
          "internetMessageId": "<***@example.com>",
          "subject": "Phishing1",
          "bodyPreview": "",
          "importance": "normal",
          "parentFolderId": "AA*****AA=",
          "conversationId": "AA*****qico=",
          "conversationIndex": "AQ*****g==",
          "isDeliveryReceiptRequested": null,
          "isReadReceiptRequested": false,
          "isRead": false,
          "isDraft": false,
          "webLink": "https://*****.com/***",
          "inferenceClassification": "focused",
          "body": {
              "contentType": "html",
              "content": "<html><head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\"><meta content=\"text/html; charset=utf-8\"></head><body><div dir=\"ltr\"><br></div></body></html>"
          },
          "sender": {
              "emailAddress": {
                  "name": "Test User",
                  "address": "***@example.com"
              }
          },
          "from": {
              "emailAddress": {
                  "name": "Test User",
                  "address": "***@example.com"
              }
          },
          "toRecipients": [
              {
                  "emailAddress": {
                      "name": "test",
                      "address": "***@example.com"
                  }
              }
          ],
          "ccRecipients": [],
          "bccRecipients": [],
          "replyTo": [],
          "flag": {
              "flagStatus": "notFlagged"
          },
          "attachments": [
              {
                  "@odata.type": "#microsoft.graph.itemAttachment",
                  "id": "***************************************",
                  "lastModifiedDateTime": "2021-05-13T21:48:49Z",
                  "name": "*****.eml",
                  "contentType": "message/rfc822",
                  "size": 44405,
                  "isInline": false
              },
              {
                  "@odata.type": "#microsoft.graph.fileAttachment",
                  "@odata.mediaContentType": "application/octet-stream",
                  "id": "***************************************",
                  "lastModifiedDateTime": "2021-05-13T21:48:49Z",
                  "name": "*****.ini",
                  "contentType": "application/octet-stream",
                  "size": 336,
                  "isInline": false,
                  "contentId": "f_*****",
                  "contentLocation": null,
                  "contentBytes": "*****="
              }
          ],
          "originalEmail": [
              {
                  "fileId": "10",
                  "fileName": "https://*****.com/***",
                  "md5": "***************************************",
                  "sha1": "***************************************",
                  "sha256": "***************************************",
                  "detail": {
                      "@odata.context": "https://*****.com/***",
                      "@odata.type": "#microsoft.graph.itemAttachment",
                      "id": "***************************************",
                      "lastModifiedDateTime": "2021-05-13T21:48:49Z",
                      "name": "*****.eml",
                      "contentType": "message/*****",
                      "size": 44405,
                      "isInline": false,
                      "***@example.com": "https://*****.com/***",
                      "***@example.com": "https://*****.com/***",
                      "item": {
                          "@odata.type": "#microsoft.graph.message",
                          "id": "",
                          "createdDateTime": "2021-05-13T21:48:49Z",
                          "lastModifiedDateTime": "2021-05-13T21:48:49Z",
                          "receivedDateTime": "2021-05-13T00:58:40Z",
                          "sentDateTime": "2021-05-13T00:58:39Z",
                          "hasAttachments": true,
                          "internetMessageId": "<***@example.com>",
                          "subject": "Attention",
                          "bodyPreview": "Important\r\n\r\nhttps://www.office.com/?auth=2",
                          "conversationId": "******=",
                          "conversationIndex": "AQ******==",
                          "isReadReceiptRequested": false,
                          "isRead": true,
                          "isDraft": false,
                          "webLink": "https://*****.com/***",
                          "internetMessageHeaders": [
                              {
                                  "name": "Delivered-To",
                                  "value": "***@example.com"
                              },
                              {
                                  "name": "Received",
                                  "value": "by ****:****:****:***::**** with SMTP id v134csp187692vkd;        Wed, 12 May 2021 ****:****:****:***::**** -0700 (PDT)"
                              }
                          ],
                          "body": {
                              "contentType": "html",
                              "content": "<html><head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\"><style type=\"text/css\" style=\"display:none;\"> P {margin-top:0;margin-bottom:0;} </style></head><body dir=\"ltr\"><div style=\"font-family: Calibri, Arial, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);\"><b>Important</b></div><div style=\"font-family: Calibri, Arial, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);\"><b><br></b></div><div style=\"font-family: Calibri, Arial, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);\"><a href=\"https://*****.com/***" id=\"LPlnk831072\">https://www.office.com/?auth=2</a></div><div style=\"font-family: Calibri, Arial, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);\"><br></div><div style=\"font-family: Calibri, Arial, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);\"><br></div></body></html>"
                          },
                          "sender": {
                              "emailAddress": {
                                  "name": "sys***",
                                  "address": "***@example.com"
                              }
                          },
                          "from": {
                              "emailAddress": {
                                  "name": "sys***",
                                  "address": "***@example.com"
                              }
                          },
                          "toRecipients": [
                              {
                                  "emailAddress": {
                                      "name": "***@example.com",
                                      "address": "***@example.com"
                                  }
                              }
                          ],
                          "flag": {
                              "flagStatus": "notFlagged"
                          },
                          "attachments": [
                              {
                                  "@odata.type": "#microsoft.graph.fileAttachment",
                                  "@odata.mediaContentType": "image/gif",
                                  "id": "***************************************",
                                  "lastModifiedDateTime": "2021-05-13T00:58:39Z",
                                  "name": "*****.gif",
                                  "contentType": "image/gif",
                                  "size": 945,
                                  "isInline": false,
                                  "contentId": "***@example.com",
                                  "contentLocation": null,
                                  "contentBytes": "******/r6+*****+/*****s="
                              },
                              {
                                  "@odata.type": "#microsoft.graph.fileAttachment",
                                  "@odata.mediaContentType": "application/octet-stream",
                                  "id": "***************************************",
                                  "lastModifiedDateTime": "2021-05-13T00:58:39Z",
                                  "name": "*****.ini",
                                  "contentType": "application/octet-stream",
                                  "size": 430,
                                  "isInline": false,
                                  "contentId": "***@example.com",
                                  "contentLocation": null,
                                  "contentBytes": "*****="
                              }
                          ]
                      }
                  }
              }
          ]
      }
  ]
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "ID": [
        "AA*****AAA="
    ],
    "InternetMessageID": [
        ""
    ]
}

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

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

Fetch Event Field Mapping

Please note that Fetch Event commands require event field mapping. Field mapping plays a key role in the data normalization process part of the event pipeline. Field mapping converts the original data fields from the different providers to the D3 fields which are standardized by the D3 Model. Please refer to Event and Incident Intake Field Mapping for details.

If you require a custom field mapping, click +Add Field to add a custom field mapping. You may also remove built-in field mappings by clicking x. Please 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 is applied when this fetch event command is executed. For out-of-the-box integrations, you will find a set of field mapping provided by the system. Default event source provides field mappings for common fields from fetched events. 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. Click Edit Event Source to view the "Main Event JSON Path". Click Edit Event Source to view the "Main Event JSON Path".
- 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
Unique Event Key	.id
Email subject	.subject
Sender	.sender.emailAddress.address
CcRecipients	.ccRecipients
Message body	.body.content
Attachment Name	.attachments.name
Recipient	.toRecipients[*].emailAddress.address
Original Email Body	.originalEmail[*].detail.item.body.content
Original Email Subject	.originalEmail[*].detail.item.subject
Original recipient	.originalEmail[].detail.item.toRecipients[].emailAddress.address
Original Email CcRecipients	.originalEmail[*].detail.item.ccRecipients
Original sender	.originalEmail[*].detail.item.sender.emailAddress.address
Event Type	*Email Alerts
Original File Name	.originalEmail[].detail.item.attachments[].name
Original File Content	.originalEmail[].detail.item.attachments[].contentBytes
Message ID	.id
Internal message ID	.internetMessageId
Importance	.importance
Description	.subject
Filename	.attachments[*].name
File Content	.attachments[*].contentBytes

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 you 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 you have defined the Filter parameter, 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>
 - https://learn.microsoft.com/en-us/graph/filter-query-parameter#syntax-for-using-the-filter-odata-query-parameter
- $search parameter is using KQL language, the basic syntax is <Property Name>:<Expression>
 - Available property names: https://learn.microsoft.com/en-us/graph/search-query-parameter
 - You may only specify a value without a specific property name. Then the default search properties are from, subject and body.
The authorized access code is user account based which cannot read/write another user account data. If your selected grant type for the connection is Authorization Code, the input parameters Email Address will use your login email address as default, so you may leave it blank. See step 3h iv c of Configuring D3 SOAR to Work with Office 365 for more about login information.
If your connection grant type is Client Credentials, you must specify the Email Address field.
Email Address is a required parameter to run this command.
- You should already have your desired email addresses on hand to run this command. If you don't, you may use the Fetch Event command with defined filters to search for the desired email addresses. They can be found in the returned raw data under the "toRecipients" key.
Email Folder is a required parameter to run this command.
- Run the List Mail Folders command to obtain Mail Folder. Please note both Mail Folder IDs and Mail Folder names are accepted.

Input

Input Parameter	Required/Optional	Description	Example
Email Address	Optional	The email address to fetch related events from. Note: This parameter can be left blank if the grant type for the connection is Authorization Code. The logged in user's email address will be used for the query. You can only use the logged in user's account mailbox for the command. To access any user mailbox with this command, you will need to select the Client Credential grant type during the initial configuration of the connection.	test@example.com
Mail Folder	Required	The mail folder to fetch emails from. Both system folders and user-created folders can be used to define this parameter. Folder ID can be used to search for both types of folder, however only system default folders can be searched by folder name. The available default folder names are "archive", "clutter", "conflicts", "conversationhistory", "deleteditems", "drafts", "inbox", "junkemail", "localfailures", "msgfolderroot", "outbox", "recoverableitemsdeletions", "scheduled", "searchfolders", "sentitems", "serverfailures" and "syncissues". Note: Spaces cannot be used in folder names. For user-created folders, the value must be the Folder ID. Mail folders can be obtained using the List Mail Folders command.	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. The default value is 10.	1
Filter	Optional	The queries to filter results. Filter is using $filter query parameter. For the $filter syntax, see Syntax for using the $filter OData query parameter from Microsoft's documentation.	createdDateTime gt 2020-04-21
Search	Optional	The search condition expression. Leave this field empty if the Filter parameter is defined. Filter is using $search query parameter. $search is using 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

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
  {
    "@odata.etag": "W/\"C******pW\"",
    "id": "***************************************",
    "createdDateTime": "2021-04-21T10:54:03Z",
    "lastModifiedDateTime": "2021-04-21T10:54:05Z",
    "changeKey": "*****",
    "categories": [],
    "receivedDateTime": "2021-04-21T10:54:03Z",
    "sentDateTime": "2021-04-21T10:54:01Z",
    "hasAttachments": false,
    "internetMessageId": "",
    "subject": "Message Center Major Change Update Notification",
    "bodyPreview": "Microsoft Graph privacy controls to fully replace the classic Office Delve control in May\r\nMC251870 Â· D3********\r\n\r\nIn August 2020, we announced that Microsoft Graph privacy controls (MC219941) would be available in the fourth quarter. These Microsoft Gra",
    "importance": "normal",
    "parentFolderId": "*****-*****=",
    "conversationId": "*****-*****=",
    "conversationIndex": "*****/*****==",
    "isDeliveryReceiptRequested": null,
    "isReadReceiptRequested": false,
    "isRead": false,
    "isDraft": false,
    "webLink": "https://*****.com/***",
    "inferenceClassification": "focused",
    "body": {
      "contentType": "html",
      "content": "\r\n\r\n<!--\r\nbody, table, td\r\n\t{font-family:Segoe UI,Helvetica,Arial,sans-serif!important}\r\na\r\n\t{color:#006CBE;\r\n\ttext-decoration:none}\r\n-->\r\n Microsoft Graph privacy controls to fully replace the classic Office Delve control in MayMC251870 Â· D3********In August 2020, we announced that Microsoft Graph privacy controls (MC219941) would be available in the fourth quarter. These Microsoft Graph privacy controls allow administrators to more granularly configure the visibility of Graph-derived insights which includes documents and sites across Microsoft 365 apps and services. We also announced a six-month transition period before the new controls would replace classic Office Delve controls. The transition and end-of-support for the classic Office Delve control and its respective settings will occur in mid-May 2021. We are also introducing controls that allow people in your organization to customize insights that are available to them and to their colleagues.  This message is associated with Microsoft 365 Roadmap ID 68863 When this will happenBefore May 15, we will transfer the opted-out statuses of any Office Delve privacy settings to the new Microsoft Graph privacy controls configuration.After May 15, you will need to use Microsoft Graph privacy controls to configure insights such as recommendations in the Outlook Mobile app and Office applications. After May 15, any Office Delve or other insights-based experiences that have been disabled will remain in a disabled state. Re-configure with Microsoft Graph privacy controls.How this will affect your organizationThe Microsoft Graph privacy controls replace and improve on existing Office Delve privacy controls with the exception of a sub-set of controls.We are also introducing controls when insights-based experiences are enabled either at the organization or to select users/groups. These controls allow your users to manage how their activities are used to calculate recommendations for themselves and their colleagues. These controls can be enabled via PowerShell: How to configure item insights setting via PowerShellWhat you need to do to prepare Review the following: If you have changed Office Delve or item insights privacy configurations within the past three months, you must thoroughly review the new item insights configuration at the administrator level. Before May 15, you must ensure that you have the correct values for new item insights settings. Our transfer process migrates a single snapshot of your Office Delve privacy configuration which may have already occurred.If you have disabled Office Delve at the organization level in the SharePoint Admin Center, we recommend implementing the Microsoft Graph privacy controls rather than the Office Delve settings. In addition, you can enable other insights-based experiences on a select group of users by using admin-controllable item insights settings.Note: Disabling Delve does not disable Microsoft Graph. Office Graph and Microsoft Graph are different concepts despite their similar names. For more info about Microsoft Graph, see Overview of Microsoft Graph.Learn moreCustomizing item insights privacy in Microsoft Graph Introducing new privacy controls with the Microsoft Graph (August 2020)View this message in the Microsoft 365 admin center You're subscribed to this email using ***@example.com. If you're an IT admin, you're subscribed by default, but you can unsubscribe at any time. If you're not an IT admin, ask your admin to remove your email address from Microsoft 365 message center preferences.How to view translated messagesThis is a mandatory service communication. To set your contact preferences or to unsubcribe from other communications, visit the Promotional Communications Manager. Privacy statement. Il sâ€™agit de communications obligatoires. Pour configurer vos prÃ©fÃ©rences de contact pour dâ€™autres communications, accÃ©dez au gestionnaire de communications promotionnelles. DÃ©claration de confidentialitÃ©. Microsoft Corporation, One Microsoft Way, Redmond WA 98052 USA  "
    },
    "sender": {
      "emailAddress": {
        "name": "Microsoft 365 Message center",
        "address": "***@example.com"
      }
    },
    "from": {
      "emailAddress": {
        "name": "Microsoft 365 Message center",
        "address": "***@example.com"
      }
    },
    "toRecipients": [
      {
        "emailAddress": {
          "name": "test",
          "address": "***@example.com"
        }
      }
    ],
    "ccRecipients": [],
    "bccRecipients": [],
    "replyTo": [],
    "flag": {
      "flagStatus": "notFlagged"
    },
    "attachments": [],
    "originalHeader": "*****"
  }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "ID": [
        "AA*****AA="
    ]
}

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

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

@ODATA.ETAG	ID	CREATEDDATETIME	LASTMODIFIEDDATETIME	CHANGEKEY	CATEGORIES	RECEIVEDDATETIME	SENTDATETIME	HASATTACHMENTS	INTERNETMESSAGEID	SUBJECT	BODYPREVIEW	IMPORTANCE	PARENTFOLDERID	CONVERSATIONID	CONVERSATIONINDEX	ISDELIVERYRECEIPTREQUESTED	ISREADRECEIPTREQUESTED	ISREAD	ISDRAFT	WEBLINK	INFERENCECLASSIFICATION	BODY	SENDER	FROM	TORECIPIENTS	CCRECIPIENTS	BCCRECIPIENTS	REPLYTO	FLAG	ATTACHMENTS	ORIGINALHEADER
W/";*****";	*-***=	4/21/2021 10:54:03 AM	4/21/2021 10:54:05 AM	***	[]	4/21/2021 10:54:03 AM	4/21/2021 10:54:01 AM	False		Message Center Major Change Update Notification		normal	*-***=	-=	*/**==		False	False	False	https://outlook.office365.com/owa/?ItemID=***%%***%3D&exvsurl=1&viewmodel=ReadMessageItem	focused		{ ";emailAddress";: { ";name";: ";Microsoft 365 Message center";, ";address";: ";test@example.com"; } }	{ ";emailAddress";: { ";name";: ";Microsoft 365 Message center";, ";address";: ";test@example.com"; } }	[ { ";emailAddress";: { ";name";: ";test";, ";address";: ";test@example.com"; } } ]	[]	[]	[]	{ ";flagStatus";: ";notFlagged"; }	[]

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 you 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 file(s) from the specified criteria and saves them to D3 SOAR's database. Corresponding fileID(s) will be returned 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 which cannot read/write another user account data. If your selected grant type for the connection is Authorization Code, the input parameters Email Addresses or User IDs will use your login email addresses or user IDs as default, so you may leave it blank. See step 3h iv c of Configuring D3 SOAR to Work with Office 365 for more about login information.
If your connection grant type is Client Credentials, you must specify the Email Addresses or User IDs field.
Your input Email Addresses or user IDs can be searched by using the "toRecipients" key in the Fetch Event Raw data JSON object.
The parameter Message IDs is required to run this command.
- You should already have your desired Message IDs on hand to run this command. If you don't, you may use the Fetch Event command with defined filters to retrieve the desired Event IDs. The Event IDs can be found in the raw data at the path $.value[*].id. Note: Both "ID" and "internetMessageId" are acceptable inputs.
- Please note that your input Message IDs must match your Email Addresses or User IDs. You can find it in raw data response. Your input "id" or "internetMessageId" must match the value of "toRecipients".
If you 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 to retrieve email attachments from.

Note: This parameter can be left blank if the grant type for the connection is Authorization Code. The logged in user's email address will be used for the query. You can only use the logged in user's account mailbox for the command. To access any user mailbox with this command, you will need to select the Client Credential grant type during the initial configuration of the connection.

[ "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 should be associated with the corresponding user ID or principal name in the array. For instance, if the message ID array has message1, message2… etc., the user ID or principal name array would be user1, user2…etc. message1 would be associated with user1, and message2 with user2 and so on.

[ "AA*****-Z*****AA=", "<Y*****01.PROD.OUTLOOK.COM>" ]

Output

Raw Data

The primary response data from the API request.

D3 enriches the raw data from the original Office 365 API response by adding the userId field to indicate the input user id and adding the messageId field to indicate the input message id.

SAMPLE DATA

JSON

[
    {
    "userId": "***@example.com",
    "messageId": "*****-*****-*****="
    "fileId ": *****,
    "fileName": "*****.txt.",
    "md5": "***************************************",
    "sha1": "***************************************",
    "Sha256": "***************************************"
    },
    {
    "userId": "***@example.com",
    "messageId": "*****-****-*****="
    "fileId ": *****,
    "fileName": "*****.txt",
    "md5": "***************************************",
    "sha1": "***************************************",
    "Sha256": "***************************************"
    },
    {
    "userId": "***@example.com",
    "messageId": ""
    "fileId ": *****,
    "fileName": "*****.doc",
    "md5": "***************************************",
    "sha1": "***************************************",
    "Sha256": "***************************************"
    }
]

Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE

[
    {
    "userId": "***@example.com",
    "messageId": "*****-*****-*****="
    "fileId ": *****,
    "fileName": "*****.txt.",
    "md5": "***************************************",
    "sha1": "***************************************",
    "Sha256": "***************************************"
    },
    {
    "userId": "***@example.com",
    "messageId": "*****-****-*****="
    "fileId ": *****,
    "fileName": "*****.txt",
    "md5": "***************************************",
    "sha1": "***************************************",
    "Sha256": "***************************************"
    },
    {
    "userId": "***@example.com",
    "messageId": ""
    "fileId ": *****,
    "fileName": "*****.doc",
    "md5": "***************************************",
    "sha1": "***************************************",
    "Sha256": "***************************************"
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "FileIDs": [
        *****
    ],
    "MD5s": [
        "*****"
    ],
    "SHA1s": [
        "*****"
    ],
    "SHA256s": [
        "*****"
    ]
}

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

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

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 you 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 email(s) in EML format from the specified criteria and saves them to D3 SOAR's database. EML files contain the contents of the email, including the subject, sender, recipient(s), date of the message and any file attachments. Corresponding fileID(s) will be returned to retrieve the EML file(s) using the Get File Content utility command.

Reader Note

The authorized access code is user account based which cannot read/write another user account data. If your selected grant type for the connection is Authorization Code, the input parameters Email Addresses or User IDs will use your login email addresses or user IDs as default, so you may leave it blank. See step 3h iv c of Configuring D3 SOAR to Work with Office 365 for more about login information.
If your connection grant type is Client Credentials, you must specify the Email Addresses or User IDs field.
Your input Email Addresses or user IDs can be searched by using the "toRecipients" key in the Fetch Event raw data JSON object.
The parameter Message IDs is required to run this command.
- You should already have your desired Message IDs on hand to run this command. If you don't, you may use the Fetch Event command with defined filters to retrieve the desired Event IDs. The Event IDs can be found in the raw data at the path $value[*].id. Note: Both "ID" and "internetMessageId" are acceptable inputs.
- Please note that your input Message IDs must match your Email Addresses or User IDs. You can find it in raw data response Your input "id" or "internetMessageId" must match the value of "toRecipients".

Input

Input Parameter

Required/Optional

Description

Example

Email Addresses or User IDs

Optional

The email addresses or user IDs to retrieve emails from.

Note: This parameter can be left blank if the grant type for the connection is Authorization Code. The logged in user's email address will be used for the query. You can only use the logged in user's account mailbox for the command. To access any user mailbox with this command, you will need to select the Client Credential grant type during the initial configuration of the connection.

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

Message IDs

Optional

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

Each message ID should be associated with the corresponding user ID or principal name in the array. For instance, if the message ID array has message1, message2… etc., the user ID or principal name array would be user1, user2…etc. message1 would be associated with user1, and message2 with user2 and so on.

[ "AA*****-ZR*****A=", "<YTO*****@*****.CANPRD01.PROD.OUTLOOK.COM>" ]

Output

Raw Data

The primary response data from the API request.

D3 enriches the raw data from the original Office 365 API response by adding the userId field to indicate the input user id and adding the messageId field to indicate the input message id.

SAMPLE DATA

JSON

[
    {
    "userId": "test@example.com",
    "messageId": "*****-*****-*****="
    "fileId ": *****,
    "fileName": "*****.eml",
    "md5": "*****",
    "sha1": "*****",
    "Sha256": "*****"
    }
]

Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE

[
    {
    "userId": "test@example.com",
    "messageId": "*****-*****-*****="
    "fileId ": *****,
    "fileName": "*****.eml",
    "md5": "*****",
    "sha1": "*****",
    "Sha256": "*****"
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "FileIDs": [
        *****
    ],
    "MD5s": [
        "*****"
    ],
    "SHA1s": [
        "*****"
    ],
    "SHA256s": [
        "*****"
    ]
}

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

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

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 you 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

Gets email message by the specified user and message ID.

Reader Note

The authorized access code is user account based which cannot read/write another user account data. If your selected grant type for the connection is Authorization Code, the input parameters Email Addresses or User IDs will use your login email addresses or user IDs as default, so you may leave it blank. See step 3h iv c of Configuring D3 SOAR to Work with Office 365 for more about login information.
If your connection grant type is Client Credentials, you must specify the Email Addresses or User IDs field.
Your input Email Addresses or user IDs can be searched by using the "toRecipients" key in the Fetch Event raw data JSON object.
The parameter Message IDs is required to run this command.
- You should already have your desired Message IDs on hand to run this command. If you don't, you may use the Fetch Event command with defined filters to retrieve the desired Event IDs. The Event IDs can be found in the raw data at the path $value[*].id. Note: Both "ID" and "internetMessageId" are acceptable inputs.
- Please note that your input Message IDs must match your Email Addresses or User IDs. You can find it in raw data response. Your input "id" or "internetMessageId" must match the value of "toRecipients".

Input

Input Parameter

Required/Optional

Description

Example

Email Addresses or User IDs

Optional

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

Note: This parameter can be left blank if the grant type for the connection is Authorization Code. The logged in user's email address will be used for the query. You can only use the logged in user's account mailbox for the command. To access any user mailbox with this command, you will need to select the Client Credential grant type during the initial configuration of the connection.

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

Message IDs

Required

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

Each message ID should be associated with the corresponding user ID or principal name in the array. For instance, if the message ID array has message1, message2… etc., the user ID or principal name array would be user1, user2…etc. message1 would be associated with user1, and message2 with user2 and so on.

[ "AA*****0-Z*****0-Z*****A=", "<YT*****@*****.CANPRD01.PROD.OUTLOOK.COM>" ]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[ {
  
  "@odata.context": "https://*****.com/***",
  "@odata.etag": "W/\"*****/*****/J7\",
  "id": "***************************************",
  "createdDateTime": "2021-08-12T22:21:24Z",
  "lastModifiedDateTime": "2021-08-12T22:21:25Z",
  "changeKey": "****/*****/J7",
  "categories": [],
  "receivedDateTime": "2021-08-12T22:21:24Z",
  "sentDateTime": "2021-08-12T22:21:22Z",
  "hasAttachments": true,
  "internetMessageId": "",
  "subject": "Eddie Test 2",
  "bodyPreview": "",
  "importance": "normal",
  "parentFolderId": "*****==",
  "conversationId": "****=",
  "conversationIndex": "*****==",
  "isDeliveryReceiptRequested": false,
  "isReadReceiptRequested": false,
  "isRead": false,
  "isDraft": false,
  "webLink": "https://*****.com/***",
  "inferenceClassification": "focused",
  "body": {
  "contentType": "html",
  "content": "\r\n\r\n<!--\r\np\r\n\t{margin-top:0;\r\n\tmargin-bottom:0}\r\n-->\r\n"
  },
  "sender": {
  "emailAddress": {
  "name": "test",
  "address": "***@example.com"
  }
  },
  "from": {
  "emailAddress": {
  "name": "test",
  "address": "***@example.com"
  }
  },
  "toRecipients": [
  {
  "emailAddress": {
  "name": "***@example.com",
  "address": "***@example.com"
  }
  },
  {
  "emailAddress": {
  "name": "***@example.com",
  "address": "***@example.com"
  }
  }
  ],
  "ccRecipients": [
  {
  "emailAddress": {
  "name": "test",
  "address": "***@example.com"
  }
  },
  {
  "emailAddress": {
  "name": "test",
  "address": "***@example.com"
  }
  }
  ],
  "bccRecipients": [],
  "replyTo": [],
  "flag": {
  "flagStatus": "notFlagged"
  }
  } 
]

Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

D3 enriches the raw data from the original Office 365 API response by adding the toRecipientAddresses field to convert the array of toRecipients.emailAddress.address to a string with a comma as delimiter, and adding ccRecipientAddresses field to convert the array of ccRecipients.emailAddress.address to a string with a comma as delimiter.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE

[ {
  "@odata.context": "https://*****.com/***",
  "@odata.etag": "W/\"*****/******************/J7\",
  "id": "***************************************",
  "createdDateTime": "2021-08-12T22:21:24Z",
  "lastModifiedDateTime": "2021-08-12T22:21:25Z",
  "changeKey": "*****/*********/J7",
  "categories": [],
  "receivedDateTime": "2021-08-12T22:21:24Z",
  "sentDateTime": "2021-08-12T22:21:22Z",
  "hasAttachments": true,
  "internetMessageId": "",
  "subject": "Eddie Test 2",
  "bodyPreview": "",
  "importance": "normal",
  "parentFolderId": "*****==",
  "conversationId": "******=",
  "conversationIndex": "*****==",
  "isDeliveryReceiptRequested": false,
  "isReadReceiptRequested": false,
  "isRead": false,
  "isDraft": false,
  "webLink": "https://*****.com/***",
  "inferenceClassification": "focused",
  "body": {
  "contentType": "html",
  "content": "\r\n\r\n<!--\r\np\r\n\t{margin-top:0;\r\n\tmargin-bottom:0}\r\n-->\r\n"
  },
  "sender": {
  "emailAddress": {
  "name": "test",
  "address": "***@example.com"
  }
  },
  "from": {
  "emailAddress": {
  "name": "test",
  "address": "***@example.com"
  }
  },
  "toRecipients": [
  {
  "emailAddress": {
  "name": "***@example.com",
  "address": "***@example.com"
  }
  },
  {
  "emailAddress": {
  "name": "***@example.com",
  "address": "***@example.com"
  }
  }
  ],
  "toRecipientAddresses":  "***@example.com, ***@example.com",
  "ccRecipients": [
  {
  "emailAddress": {
  "name": "test",
  "address": "***@example.com"
  }
  },
  {
  "emailAddress": {
  "name": "test",
  "address": "***@example.com"
  }
  }
  ],
  "ccRecipientAddresses": "***@example.com, ***@example.com",
  "bccRecipients": [],
  "replyTo": [],
  "flag": {
  "flagStatus": "notFlagged"
  }
  } 
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "Subjects": [
        "user Test 2"
    ],
    "Senders": [
        "test@example.com"
    ],
    "ToRecipients": [
        "test1@example.com,test@example.com"
    ],
    "CCRecipients": [
        "test1@example.com,test@example.com"
    ]
}

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

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

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 you 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 which cannot read/write another user account data. If your selected grant type for the connection is Authorization Code, the input parameters Email Addresses or User IDs will use your login email addresses or user IDs as default, so you may leave it blank. See step 3h iv c of Configuring D3 SOAR to Work with Office 365 for more about login information.
If your connection grant type is Client Credentials, you must specify the Email Addresses or User IDs field.
You should already have your desired email addresses or user IDs on hand to run this command. If you don't, you may use the Fetch Event command with defined filters to retrieve the desired values. They will be returned under the "toRecipients" key in the returned JSON object.

Input

Input Parameter

Required/Optional

Description

Example

Email Addresses or User IDs

Optional

The email addresses or user IDs to list mail folders.

Note: This parameter can be left blank if the grant type for the connection is Authorization Code. The logged in user's email address will be used for the query. You can only use the logged in user's account mailbox for the command. To access any user mailbox with this command, you will need to select the Client Credential grant type during the initial configuration of the connection.

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

Include Hidden Folders

Optional

The option to include hidden folders in the returned list.

false

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
  "@odata.context": "https://*****.com/***",
  "value": [
      {
          "id": "***************************************",
          "displayName": "Sent Items",
          "parentFolderId": "*****-*****=",
          "childFolderCount": 0,
          "unreadItemCount": 0,
          "totalItemCount": 147,
          "sizeInBytes": 63743210,
          "isHidden": false
      },
      {
          "id": "***************************************",
          "displayName": "Social Activity Notifications",
          "parentFolderId": "*****-*****=",
          "childFolderCount": 0,
          "unreadItemCount": 0,
          "totalItemCount": 0,
          "sizeInBytes": 0,
          "isHidden": true
      }
  ],
  "@odata.nextLink": "https://*****.com/***"
}

Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

D3 customizes the Context Data by extracting the data from path $.value in API returned JSON.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE

[
      {
          "id": "***************************************",
          "displayName": "Sent Items",
          "parentFolderId": "*****-*****=",
          "childFolderCount": 0,
          "unreadItemCount": 0,
          "totalItemCount": 147,
          "sizeInBytes": 63743210,
          "isHidden": false
      },
      {
          "id": "***************************************",
          "displayName": "Social Activity Notifications",
          "parentFolderId": "*****-*****=",
          "childFolderCount": 0,
          "unreadItemCount": 0,
          "totalItemCount": 0,
          "sizeInBytes": 0,
          "isHidden": true
      }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "MailFolderIDs": [
        "*****-*****="
    ],
    "MailFolderNames": [
        "*****-*****="
    ]
}

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

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

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 you 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.

Move Email Messages

Moves the specified messages to the destination mail folder.

Reader Note

The authorized access code is user account based which cannot read/write another user account data. If your selected grant type for the connection is Authorization Code, the input parameters Email Addresses or User IDs will use your login email addresses or user IDs as default, so you may leave it blank. See step 3h iv c of Configuring D3 SOAR to Work with Office 365 for more about login information.
If your connection grant type is Client Credentials, you must specify the Email Addresses or User IDs field.
Your input Email Addresses or user IDs can be searched by using the "toRecipients" key in the Fetch Event raw data JSON object.
The parameter Message IDs is required to run this command.
- You should already have your desired Message IDs on hand to run this command. If you don't, you may use the Fetch Event command with defined filters to retrieve the desired Event IDs. The Event IDs can be found in the raw data at the path $value[*].id. Note: Both "ID" and "internetMessageId" are acceptable inputs.
- Please note that your input Message IDs must match your Email Addresses or User IDs. You can find it in raw data response., Your input "id" or "internetMessageId" must match the value of "toRecipients".
Destination Mail Folder is a required parameter to run this command.
- Run the List Mail Folders command to obtain destination mail folders. Please note that both Mail Folder IDs and Mail Folder names are accepted.

Input

Input Parameter	Required/Optional	Description	Example
Email Addresses or User IDs	Optional	The email addresses or user IDs to move email messages. Note: This parameter can be left blank if the grant type for the connection is Authorization Code. The logged in user's email address will be used for the query. You can only use the logged in user's account mailbox for the command. To access any user mailbox with this command, you will need to select the Client Credential grant type during the initial configuration of the connection.	[ "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 should be associated with the corresponding user ID or principal name in the array. For instance, if the message ID array has message1, message2… etc., the user ID or principal name array would be user1, user2…etc. message1 would be associated with user1, and message2 with user2 and so on.	[ "AA*****AAA" ]
Destination Mail Folder	Required	The name of the destination mail folder to move the messages to. Mail folder names can be obtained using the List Mail Folders command.	archive

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
  {
      "@odata.context": "https://*****.com/***",
      "@odata.etag": "W/\"*****/\"",
      "id": "***************************************",
      "createdDateTime": "2021-09-13T18:57:24Z",
      "lastModifiedDateTime": "2021-09-21T19:01:51Z",
      "changeKey": "****/",
      "categories": [],
      "receivedDateTime": "2021-09-13T18:57:25Z",
      "sentDateTime": "2021-09-13T18:57:23Z",
      "hasAttachments": false,
      "internetMessageId": "<*****-*****=@microsoft.com>",
      "subject": "Message Center Major Change Update Notification",
      "bodyPreview": "Excel Power View Retirement\r\nMC284624 Ã‚Â· D3********\r\n\r\nSilverlight, a component used in Power View, will no longer be supported beginning on October 12th. In response, we will be starting the process to retire Power View from Microsoft 365. As an alternati",
      "importance": "normal",
      "parentFolderId": "*****-****=",
      "conversationId": "*****=",
      "conversationIndex": "*****==",
      "isDeliveryReceiptRequested": null,
      "isReadReceiptRequested": false,
      "isRead": false,
      "isDraft": false,
      "webLink": "https://*****.com/***",
      "inferenceClassification": "other",
      "body": {
          "contentType": "html",
          "content": "\r\n\r\n<!--\r\nbody, table, td\r\n\t{font-family:Segoe UI,Helvetica,Arial,sans-serif!important}\r\na\r\n\t{color:#006CBE;\r\n\ttext-decoration:none}\r\n-->\r\n Excel Power View RetirementMC284624 Ã‚Â· D3********Silverlight, a component used in Power View, will no longer be supported beginning on October 12th. In response, we will be starting the process to retire Power View from Microsoft 365. As an alternative to Power View, we recommend using Power BI Desktop, which is where we will continue to invest our development resources.Key points:Timing: Beginning October 12, 2021 this change will roll out as an update. Action: Inform users of the retirement and direct them to utilize Power BI Desktop as an alternative.How this will affect your organization: Once users have taken the update they will no longer be able to create or open Power View reports from Excel. What you need to do to prepare: Instead of using Power View, we recommend using other ways to do analysis and visualizations within Excel (For example, PivotTables, PivotCharts, and so on). For more information, see BI capabilities in Excel and Office 365, or you can use Power BI Desktop (a free download). Existing Power View reports can be opened in Power BI, and new reports can be created in Power BI from Excel data. Please click Additional Information to learn more. Additional Information View this message in the Microsoft 365 admin center You're subscribed to this email using ***@example.com. If you're an IT admin, you're subscribed by default, but you can unsubscribe at any time. If you're not an IT admin, ask your admin to remove your email address from Microsoft 365 message center preferences.How to view translated messagesThis is a mandatory service communication. To set your contact preferences or to unsubcribe from other communications, visit the Promotional Communications Manager. Privacy statement. Il sÃ¢â‚¬â„¢agit de communications obligatoires. Pour configurer vos prÃƒÂ©fÃƒÂ©rences de contact pour dÃ¢â‚¬â„¢autres communications, accÃƒÂ©dez au gestionnaire de communications promotionnelles. DÃƒÂ©claration de confidentialitÃƒÂ©. Microsoft Corporation, One Microsoft Way, Redmond WA 98052 USA  "
      },
      "sender": {
          "emailAddress": {
              "name": "Microsoft 365 Message center",
              "address": "***@example.com"
          }
      },
      "from": {
          "emailAddress": {
              "name": "Microsoft 365 Message center",
              "address": "***@example.com"
          }
      },
      "toRecipients": [
          {
              "emailAddress": {
                  "name": "test",
                  "address": "***@example.com"
              }
          }
      ],
      "ccRecipients": [],
      "bccRecipients": [],
      "replyTo": [],
      "flag": {
          "flagStatus": "notFlagged"
      }
  }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "MessageIDs": [
        "*****-*****="
    ],
    "ChangeKeys": [
        "*****/"
    ]
}

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

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

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 you 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 user(s).

Input

Input Parameter

Required/Optional

Description

Example

User ID or Email Address

Required

The IDs or Principal Names of the users to remove licenses.

[

"test@example.com"

]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

No Sample Data

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

No Sample Data

Return Data

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

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

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

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

results

{'@odata.context': 'https://graph.microsoft.com/v1.0/$metadata#users(userPrincipalName,displayName,id,accountEnabled,assignedLicenses,assignedPlans,companyName)/$entity', 'userPrincipalName': 'test@example.com', 'displayName': 'Phish', 'id': '***-***-***-***-***', 'accountEnabled': True, 'companyName': None, 'assignedLicenses': [], 'assignedPlans': [{'assignedDateTime': '2023-10-19T20:14:08.1179259Z', 'capabilityStatus': 'Deleted', 'service': 'SharePoint', 'servicePlanId': '***-***-***-***-***'}, {'assignedDateTime': '2023-10-19T20:14:08.1179259Z', 'capabilityStatus': 'Deleted', 'service': 'MicrosoftCommunicationsOnline', 'servicePlanId': '***-***-**-***-***'}, {'***': '2023-10-19T20:14:08.1179259Z', 'capabilityStatus': 'Deleted', 'service': 'exchange', 'servicePlanId': '***-***-**-***-***'}, {'assignedDateTime': '2023-10-19T20:14:08.1179259Z', 'capabilityStatus': 'Deleted', 'service': 'YammerEnterprise', 'servicePlanId': '***-***-**-***-***'}, {'assignedDateTime': '2023-10-19T20:14:08.1179259Z', 'capabilityStatus': 'Deleted', 'service': 'SharePoint', 'servicePlanId': '***-***-**-***-***'}, {'assignedDateTime': '2023-10-19T20:14:08.1179259Z', 'capabilityStatus': 'Deleted', 'service': 'Sway', 'servicePlanId': '***-***-**-***-***'}, {'assignedDateTime': '2023-10-19T20:14:08.1179259Z', 'capabilityStatus': 'Deleted', 'service': 'ProjectWorkManagement', 'servicePlanId': '***-***-**-***-***'}, {'assignedDateTime': '2023-10-19T20:14:08.1169263Z', 'capabilityStatus': 'Deleted', 'service': 'TeamspaceAPI', 'servicePlanId': '***-***-**-***-***'}, {'assignedDateTime': '2023-10-19T20:14:08.1169263Z', 'capabilityStatus': 'Deleted', 'service': 'PowerAppsService', 'servicePlanId': '***-***-**-***-***'}, {'assignedDateTime': '2023-10-19T20:14:08.1169263Z', 'capabilityStatus': 'Deleted', 'service': 'ProcessSimple', 'servicePlanId': '***-***-**-***-***'}, {'assignedDateTime': '2023-10-19T20:14:08.1169263Z', 'capabilityStatus': 'Deleted', 'service': 'OfficeForms', 'servicePlanId': '***-***-**-***-***'}, {'assignedDateTime': '2023-10-19T20:14:08.1169263Z', 'capabilityStatus': 'Deleted', 'service': 'To-Do', 'servicePlanId': '***-***-**-***-***'}, {'assignedDateTime': '2023-10-19T20:14:08.1169263Z', 'capabilityStatus': 'Deleted', 'service': 'MicrosoftOffice', 'servicePlanId': '***-***-**-***-***'}, {'assignedDateTime': '2023-10-19T20:14:08.1169263Z', 'capabilityStatus': 'Deleted', 'service': 'MicrosoftStream', 'servicePlanId': '***-***-**-***-***'}, {'assignedDateTime': '2023-10-19T20:14:08.1169263Z', 'capabilityStatus': 'Deleted', 'service': 'MicrosoftKaizala', 'servicePlanId': '***-***-**-***-***'}, {'assignedDateTime': '2023-10-19T20:14:08.1169263Z', 'capabilityStatus': 'Deleted', 'service': 'exchange', 'servicePlanId': '***-***-**-***-***'}, {'assignedDateTime': '2023-10-19T20:14:08.1169263Z', 'capabilityStatus': 'Deleted', 'service': 'WhiteboardServices', 'servicePlanId': '***-***-**-***-***'}, {'assignedDateTime': '2023-10-19T20:14:08.1169263Z', 'capabilityStatus': 'Deleted', 'service': 'CRM', 'servicePlanId': '***-***-**-***-***'}, {'assignedDateTime': '2023-10-19T20:14:08.1169263Z', 'capabilityStatus': 'Deleted', 'service': 'ProjectProgramsAndPortfolios', 'servicePlanId': '***-***-**-***-***'}, {'assignedDateTime': '2023-10-19T20:14:08.1169263Z', 'capabilityStatus': 'Deleted', 'service': 'CRM', 'servicePlanId': '***-***-**-***-***'}, {'assignedDateTime': '2023-10-19T20:14:08.1169263Z', 'capabilityStatus': 'Deleted', 'service': '*****', 'servicePlanId': '***-***-**-***-***'}, {'assignedDateTime': '2023-10-19T20:14:08.115926Z', 'capabilityStatus': 'Deleted', 'service': 'LearningAppServiceInTeams', 'servicePlanId': '***-***-**-***-***'}, {'assignedDateTime': '2023-10-19T20:14:08.115926Z', 'capabilityStatus': 'Deleted', 'service': 'exchange', 'servicePlanId': '***-***-**-***-***'}, {'assignedDateTime': '2023-10-19T20:14:08.115926Z', 'capabilityStatus': 'Deleted', 'service': 'YammerEnterprise', 'servicePlanId': '***-***-**-***-***'}]}

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 you 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.

Report Emails

Reports emails as phishing or spam. Note: This command is only available to use when using a connection with the Authorization Code grant type. In addition, the ThreatAssessment.ReadWrite.All permission scope must be granted.

Reader Note

The connection you use for this command must be the Authorization Code grant type.
Your input User ID or Email Address must match the one you used to configure the connection.
The parameter Message IDs is required to run this command.
- You should already have your desired Message IDs on hand to run this command. If you don't, you may use the Fetch Event command with defined filters to retrieve the desired Event IDs. The Event IDs can be found in the raw data at the path $value[*].id. Note: Both "ID" and "internetMessageId" are acceptable inputs.

Input

Input Parameter	Required/Optional	Description	Example
User ID or Email Address	Required	The user ID or email addresses to report emails from. Note: You can only report emails in the logged in user's account of the connection you are using.	test@example.com
Message IDs	Required	The IDs of the messages to report. Message IDs can be obtained using the Fetch Event command. The returned Key Fields with the JSON path $.ID will show the message IDs. Each message can only be submitted once. An error message will return if you attempt to submit it multiple times.	["A*****AA="]
Category	Required	The category (i.e., phishing or spam) of the reported emails. The default value is Phishing.	Phishing

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#informationProtection/threatAssessmentRequests/$entity",
        "@odata.type": "#microsoft.graph.mailAssessmentRequest",
        "id": "cbb54ceb-****-****-****-*****",
        "createdDateTime": "2022-03-16T18:08:06.6405477Z",
        "contentType": "mail",
        "expectedAssessment": "block",
        "category": "phishing",
        "status": "pending",
        "requestSource": "test",
        "recipientEmail": "test@example.com",
        "destinationRoutingReason": "none",
        "messageUri": "https://graph.microsoft.com/v1.0/users/*****-****-****-****-****/messages/****-****=",
        "createdBy": {
            "user": {
                "id": "84d5cca5-****-****-****-*****",
                "displayName": "actas1(oid:*****-***-****-***-***)"
            }
        }
    }
]

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "RequestIDs": [
        "***-****-****-****-***"
    ],
    "Statuses": [
        "pending"
    ]
}

Return Data

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

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

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

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

@ODATA.CONTEXT	@ODATA.TYPE	ID	CREATEDDATETIME	CONTENTTYPE	EXPECTEDASSESSMENT	CATEGORY	STATUS	REQUESTSOURCE	RECIPIENTEMAIL	DESTINATIONROUTINGREASON	MESSAGEURI	CREATEDBY
https://graph.microsoft.com/v1.0/$metadata#informationProtection/threatAssessmentRequests/$entity	#microsoft.graph.mailAssessmentRequest	cbb54ceb-**--**-08da0777ebe3	2022-03-16T18:08:06.6405477Z	mail	block	phishing	pending	administrator	test@example.com	none	https://graph.microsoft.com/v1.0/users/84d5cca5-**---a875799d1fad/messages/*-***=	{'user': {'id': '84d5cca5-**---', 'displayName': 'actas1(oid:----*)'}}

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 you 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 satisfied messages to another folder within the specified user's mailbox in Office 365.

Reader Note

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

Run the List Mail Folders command to obtain Destination Mail Folder IDs. Destination Mail Folder IDs can be Mail folder names or IDs.
- Mail folder names can be found in the returned raw data at the path $.value[*].displayName; Mail folder IDs can be found in the returned raw data at the path $.value[*].id.

Input

Input Parameter	Required/Optional	Description	Example
Email Address	Optional	The email address specified to search messages. Note: This parameter can be left blank if the grant type for the connection is Authorization Code. The logged in user's email address will be used for the query. You can only use the logged in user's account mailbox for the command. This parameter must be specified if the grant type for the connection is Client Credential. To access any user mailbox with this command, you will need to select this grant type during the initial configuration of the connection.	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 ID	Required	The name or ID of the destination mail folder in which to move the messages to. Mail folder names or IDs can be obtained using the List Mail Folders command. Please note that only well-known names can be used, otherwise please use the ID of the folder. Please refer to Microsoft for well-known folder names: mailFolder resource type - Microsoft Graph v1.0.	Archive

Output

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

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "Results": [
        {
            "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('sys***%40d3********.onmicrosoft.com')/messages/$entity",
            "@odata.etag": "W/\"CQA*************2e0\"",
            "id": "AAM*************************AA=",
            "createdDateTime": "2023-12-06T13:17:30Z",
            "lastModifiedDateTime": "2024-03-27T23:30:41Z",
            "changeKey": "CQA*************2e0",
            "categories": [],
            "receivedDateTime": "2023-12-06T13:17:30Z",
            "sentDateTime": "2023-12-06T13:17:14Z",
            "hasAttachments": false,
            "internetMessageId": "<f23********449@az.northcentralus.microsoft.com>",
            "subject": "Microsoft Entra ID Protection Weekly Digest",
            "bodyPreview": "See your Microsoft Entra ID Protection Weekly Digest report\r\n\r\n        Azure Active Directory is now Microsoft Entra ID. Learn More.\r\nMicrosoft Entra ID Protection Weekly Digest\r\n\r\nD3********\r\n\r\nNew risky users detected\r\n\r\n\r\n0\r\n\r\n\r\nNew risky sign-ins dete",
            "importance": "normal",
            "parentFolderId": "AAMk**************************AA=",
            "conversationId": "AAQ************************50=",
            "conversationIndex": "AQH*****************Q==",
            "isDeliveryReceiptRequested": null,
            "isReadReceiptRequested": false,
            "isRead": false,
            "isDraft": false,
            "webLink": "https://outlook.office365.com/owa/?ItemID=AAMk********************A%3D&exvsurl=1&viewmodel=ReadMessageItem",
            "inferenceClassification": "focused",
            "body": {
                "contentType": "html",
                "content": "<html> ... </html>"
            },
            "sender": {
                "emailAddress": {
                    "name": "Microsoft Security",
                    "address": "**********-noreply@microsoft.com"
                }
            },
            "from": {
                "emailAddress": {
                    "name": "Microsoft Security",
                    "address": "**********-noreply@microsoft.com"
                }
            },
            "toRecipients": [
                {
                    "emailAddress": {
                        "name": "sys***",
                        "address": "sys***@d3*******.onmicrosoft.com"
                    }
                }
            ],
            "ccRecipients": [],
            "bccRecipients": [],
            "replyTo": [],
            "flag": {
                "flagStatus": "notFlagged"
            }
        }
    ],
    "D3Errors": []
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "SenderEmailAddresses": [
        "**********-noreply@microsoft.com"
    ],
    "Subjects": [
        "Microsoft Entra ID Protection Weekly Digest"
    ],
    "ParentFolderIDs": [
        "AAMk**************************AA="
    ]
    
}

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

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 you 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 which cannot read/write another user account data. If your selected grant type for the connection is Authorization Code, the input parameters Sender Email will use your login email addresses as default, so you may leave it blank. See step 3h iv c of Configuring D3 SOAR to Work with Office 365 for more about login information.
If your connection grant type is Client Credentials, you must specify the Sender Email field.
If you want to assign values to the CC Recipients and BCC Recipients fields, select "No Reply" for the Reply Mode parameter.

Input

Input Parameter	Required/Optional	Description	Example
Sender Email	Optional	The email address that the email is sent from. Note: This parameter can be left blank if the grant type for the connection is Authorization Code. The logged in user's email address will be used for the query. You can only use the logged in user's account mailbox for the command. To access any user mailbox with this command, you will need to select the Client Credential grant type during the initial configuration of the connection.	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 To recipients of the email.	["test@example.com"]
CC Recipients	Optional	The CC recipients of the email. Note: If the CC recipients are specified, the Reply Mode parameter must be set to "No Reply".	["test@example.com"]
BCC Recipients	Optional	The BCC recipients of the email. Note: If the BCC recipients are specified, the Reply Mode parameter must be set to " No Reply".	["test@example.com"]
File IDs	Optional	Selects the file path according to the file source. The options for file paths are: Incident Attachment: Incident.file.file ID Playbook File: Task output Artifact File: Incident.Events.file.file ID	[ "278" ]
File Source	Optional	The file source of the file to send. The options for file sources are: Incident Attachment File: Manually uploaded file from Incident Playbook File: Output from another Task Artifact File: Ingested Artifact in an Event	Incident Attachment File
Reply Mode	Optional	The reply mode of the email.	Require Reply
Reply Due Time	Optional	The duration (in minutes) to wait for a reply.	10

Output

Raw Data

The primary response data from the API request.

D3 customizes the Raw Data by adding some key values including information pertaining to time, recipients, and delivery status.

SAMPLE DATA

JSON

{
    "sentTime": "2022-01-04 23:10:31 UTC",
    "dueTime": "2022-01-06 23:36:21 UTC",
    "replyMode": "",
    "sent_count": 2,
    "state": "Sent",
    "to": [
        {
            "sent": true,
            "email": "test@example.com"
        },
        {
            "sent": true,
            "email": "test1@example.com"
        }
    ]
}

Context Data

The data extracted from Raw Data converted into JSON format. Context Data may be identical to Raw Data in some cases.

D3 customizes the Context Data by adding some key values including information pertaining to time, recipients, and delivery status.

It is recommended to refer to the Raw Data instead of Context Data, since it contains the complete API response data. D3 will deprecate Context Data in the future, and playbook tasks using Context Data will be replaced with Raw Data.

SAMPLE DATA

CODE

{
    "sentTime": "2022-01-04 23:10:31 UTC",
    "dueTime": "2022-01-06 23:36:21 UTC",
    "replyMode": "",
    "sent_count": 2,
    "state": "Sent",
    "to": [
        {
            "sent": true,
            "email": "test@example.com"
        },
        {
            "sent": true,
            "email": "test1@example.com"
        }
    ]
}

Key Fields

Common cyber security indicators such as unique IDs, file hash values, CVE numbers, IP addresses, etc., will be extracted from Raw Data as Key Fields.
The system stores these key fields in the path $.[playbookTask].outputData. You can use these key-value pairs as data points for playbook task inputs.

SAMPLE DATA

CODE

{
    "SentTime": "2022-01-06 22:36:21 UTC",
    "DueTime": "2022-01-07 17:08:21 UTC",
    "ReplyMode": "RequireReply",
    "SentCount": 2,
    "State": "Sent",
    "ToAddresses": "test1@example.com, test2@example.com"
}

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

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

CODE

No Sample Data

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 you 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 auto reply settings for the specified account(s).

Input

Input Parameter	Required/Optional	Description	Example
User IDs Or User Principal Names	Required	The IDs or Principal Names of the users to set up auto reply.	[ "test@example.com" ]
Status	Optional	The configurations status for automatic replies. The possible values are: Disabled, Always Enabled, Scheduled. If this parameter is not defined, the default value is AlwaysEnabled.	Scheduled
Scheduled Start Time	Optional	The date and time that automatic replies are set to start (in UTC time), if Status is set to Scheduled. If this parameter is not defined, the existing scheduled start time will be used.	2023-10-10 00:00
Scheduled End Time	Optional	The date and time that automatic replies are set to end (in UTC time), if Status is set to Scheduled. If this parameter is not defined, the existing scheduled end time will be used.	2023-10-20 00:00
Internal Reply Message	Optional	The automatic reply to send to the audience internal to the signed-in user's organization, if Status is AlwaysEnabled or Scheduled. If this parameter is not defined, the existing internal reply message will be used.	<html>\n<body>\n<p>I'm at our company's worldwide reunion and will respond to your message as soon as I return.<br>\n</p></body>\n</html>\n
External Reply Message	Optional	The automatic reply to send to the specified external audience, if Status is AlwaysEnabled or Scheduled. If this parameter is not defined, the existing external reply message will be used.	<html>\n<body>\n<p>I'm at the Contoso worldwide reunion and will respond to your message as soon as I return.<br>\n</p></body>\n</html>\n

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "results": [
        {
            "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('support%40d3soar.com')/mailboxSettings",
            "userPurpose": "unknown",
            "automaticRepliesSetting": {
                "status": "scheduled",
                "externalAudience": "all",
                "internalReplyMessage": "<html>\n<body>\n<p>I'm at our company's worldwide reunion and will respond to your message as soon as I return.<br>\n</p></body>\n</html>\n",
                "externalReplyMessage": "<html>\n<body>\n<p>I'm at the Contoso worldwide reunion and will respond to your message as soon as I return.<br>\n</p></body>\n</html>\n",
                "scheduledStartDateTime": {
                    "dateTime": "2023-10-10T00:00:00.0000000",
                    "timeZone": "UTC"
                },
                "scheduledEndDateTime": {
                    "dateTime": "2023-10-20T23:59:59.0000000",
                    "timeZone": "UTC"
                }
            }
        }
    ]
}

Return Data

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

The Partially Successful state only occurs when a command’s input accepts an array of items (e.g. an array of IP addresses) and one or more items within the array return an error from the API request.

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

You can view more details about an error in the Error tab.

Return Data can be passed down directly to a subsequent command or used to create conditional tasks in playbooks.

SAMPLE DATA

CODE

Successful

Result

Provides a brief summary of outputs in an HTML formatted table.

SAMPLE DATA

results

{'@odata.context': "https://graph.microsoft.com/v1.0/$metadata#users('support%40d3soar.com')/mailboxSettings", 'userPurpose': 'unknown', 'automaticRepliesSetting': {'status': 'scheduled', 'externalAudience': 'all', 'internalReplyMessage': "<html>\n<body>\nI'm at our company's worldwide reunion and will respond to your message as soon as I return. \n</body>\n</html>\n", 'externalReplyMessage': "<html>\n<body>\nI'm at the Contoso worldwide reunion and will respond to your message as soon as I return. \n</body>\n</html>\n", 'scheduledStartDateTime': {'dateTime': '2023-10-10T00:00:00.0000000', 'timeZone': 'UTC'}, 'scheduledEndDateTime': {'dateTime': '2023-10-20T23:59:59.0000000', 'timeZone': 'UTC'}}}

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 you 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 you to perform a health check on an integration connection. You can schedule a periodic health check by selecting Connection Health Check when editing an integration connection.

Input

N/A

Output

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

You can view more details about an error in the Error tab.

SAMPLE DATA

CODE

Successful

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 you 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: Please check if you have put your callback URL to Redirect URI in Office 365. Please refer to step 3h iv of Configuring D3 SOAR to Work with Office 365 for more information.