Microsoft Exchange Server

LAST UPDATED: NOV 1, 2024

Overview

Microsoft Exchange Server is a mail server and calendaring server that runs exclusively on Windows Server operating systems. The Exchange Web Service integration supports on-premise Microsoft Exchange 2007-2016 server or Office365 using Exchange Web Services (EWS).

D3 SOAR is providing REST operations to function with Microsoft Exchange Server.

Microsoft Exchange Server is available for use in:

D3 SOAR	V12.7.127.0+
Category	Email Messaging
Deployment Options	Option I, Option III

Connection

To connect to Microsoft Exchange Server from D3 SOAR, please follow this part to collect the required information below:

Parameter	Description	Example
Server URL	The URL of the Microsoft Exchange server.	https://*...*/ews/Exchange.asmx
Domain & Username	The domain and username to authenticate with the email server. Use the following input format: [Domain]/[Username], (e.g. d3cyber7/administrator).	d3cyber7/administrator
Password	The password to authenticate with the mail server.	**********
Operational Email	The email address used to operate the connection. If a value is provided for this parameter, all commands will use the specified value for the "Exchange Email" parameter and cannot override it with their own parameter values. If you have eDiscovery permission and intend to operate on multiple email addresses, please leave this parameter blank. In such cases, the input value of the commands' "Exchange Email" parameter can be configured.	***@*.*

Permission Requirements

Each endpoint in the Microsoft Exchange Server API requires the Mailbox Search permission scope.

As Microsoft Exchange Server is using role-based access control (RBAC), the D3 connector will be generated based on a specific user account and the application. Therefore, the command permissions are inherited from the user account’s role. Users need to configure their user profile from the Microsoft Exchange Server console for each command in this integration.

READER NOTE

Please note that if you want to change a user role, it may take a long time for the connector to update. It is suggested to create a new user with the desired role in this case. Please refer to Permissions: Exchange 2013 Help | Microsoft Learn for more information on roles.

Configuring Microsoft Exchange Server to Work with D3 SOAR

Log in to your Exchange admin center with your credentials.

Creating a New User (Optional)

Go to Recipients and click on +. Select User mailbox to create a new user.
Provide the necessary information and click Save to finish creating the user. Note down the user logon name as it will be required for the D3 connection parameter (Domain & Username).

Creating and Assigning Customized Roles to Users

Go to Permissions and click on +.
Give a name to your role, then click on + under Roles. This will open a window. From the window, select the Mailbox Search role. Click Add and then OK. Repeat the same steps to select the appropriate members (choose the user you just created). Finally, click Save to save the settings.

Configuring D3 SOAR to Work with Microsoft Exchange Server

Log in to D3 SOAR.
Find the Microsoft Exchange Server integration.
1. Navigate to Configuration on the top header menu.
2. Click on the Integration icon on the left sidebar.
3. Type Microsoft Exchange Server in the search box to find the integration, then click it to select it.
4. Click + Connection, on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to Microsoft Exchange Server.
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. Tenant (Optional): When configuring the connection from a master tenant site, you have the option to choose the specific tenant sites you want to share the connection with. Once you enable this setting, you can filter and select the desired tenant sites from the dropdowns to share the connection.
7. Configure User Permissions: Defines which users have access to the connection.
8. Active: Check the tick box to ensure the connection is available for use.
9. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
  1. Input the domain level Server URL.
  2. Input the saved Domain and Username. Copy the Domain from the Microsoft Exchange Server platform (Refer to Configuring Microsoft Exchange Server to Work with D3 SOAR).
  3. Input the Password from the Microsoft Exchange Server platform (Refer to Configuring Microsoft Exchange Server to Work with D3 SOAR).
  4. Input the Operational Email.
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.
11. 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.
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

Microsoft Exchange Server 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 Microsoft Exchange Server API, please refer to the Microsoft Exchange Server API reference.

READER NOTE

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

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.

Block Emails

Moves emails matching the specified criteria to the Junk folder.

READER NOTE

The parameter Message IDs is optional to run this command.
- Run the Search All Emails command to obtain Message IDs. Message IDs can be found from the returned raw data at the path $[*].messageId.
Once an email has been blocked, it cannot be blocked again. If the defined filters are referencing the same blocked email(s), the command will run successfully with no results.
If you want to input the Message ID, ensure the ID is enclosed within "<>" brackets (e.g.<*****@*****.***l>).
At least one input parameter must be defined in order to run the command successfully.

Input

Input Parameter	Required /Optional	Description	Example
Subject	Optional	The email subject to filter emails to block.	attached
Content	Optional	The email message content to filter emails to block.	search mail test1
Attachment Name	Optional	The attachment name to filter emails to block.	.jpg
Sender Mail Address	Optional	The full sender email address to filter emails to block.	***@*.*
Message IDs	Optional	The message IDs to filter emails to block. Message IDs can be obtained using the Search All Emails command. Note: The input message IDs must be enclosed within "<>" brackets.	["<***@*.*l>"]
Exchange Email	Optional	The email address from which to block incoming emails. Note: If you have specified the "Operational Email" parameter while creating the connection, the email address associated with that parameter will be used for blocking emails.	***@*.*

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "subject": "search mail test1",
        "content": "search mail test1\r\n",
        "sender": "*****@*****.***",
        "recipients": [
            "*****@*****.***"
        ],
        "attachment_name": "123.jpg",
        "datetime_received_utc": "2021-1-28 22:5:8:0",
        "status": "in junk",
        "messageId": "<*****@*****.***l>",
        "isRead": false
    }
]

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

[
    {
        "subject": "search mail test1",
        "content": "search mail test1\r\n",
        "sender": "*****@*****.***",
        "recipients": [
            "*****@*****.***"
        ],
        "attachment_name": "123.jpg",
        "datetime_received_utc": "2021-1-28 22:5:8:0",
        "status": "in junk",
        "messageId": "<*****@*****.***l>",
        "isRead": false
    }
]

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

SUBJECT	CONTENT	SENDER	RECIPIENTS	DATETIME_RECEIVED_UTC	ATTACHMENTIDS	ATTACHMENTNAMES	STATUS	MESSAGEID	ISREAD
Teng Test 2021-10-01	This is a Test, Hello The World!!	***@*.*	['***@*.*']	2021-10-1 18:5:28:0	[]	[]	in junk	<***@*.*>	True

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.	Block 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 Microsoft Exchange Server 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: Please input at least one parameter.

Error Sample Data

Block Emails failed.

Status Code: 400.

Message: Please input at least one parameter.

Fetch Event

Fetches emails from Microsoft Exchange Server with the specified email address based on the given search criteria.

READER NOTE

Invalid filters will result in the command running successfully with no results.

Input

Input Parameter	Required /Optional	Description	Example
Start Time	Required	The start time of the time range to fetch emails, in UTC time.	2021-05-25 00:00
End Time	Required	The end time of the time range to fetch emails, in UTC time.	2021-05-26 00:00
Number of Event(s) Fetched	Optional	The maximum number of emails to retrieve from each accessible mailbox if the parameter Exchange Email is not defined. The number of returned records may exceed the default or specified input value. The default value is 20.	20
Search Condition	Optional	The QuerySet filter condition, based on Django-like syntax, to filter emails to fetch. For example, "subject__contains='Foo'" and "subject__icontains='bar'". For more information on additional Django filter keywords, please refer to QuerySet API reference \| Django documentation. Note: The filter condition does not support '__endswith', '__iendswith', '__year', and other date-related lookups.	subject__contains="Foo"
Exchange Email	Optional	The email address to retrieve email messages from. Note: If you have specified the "Operational Email" parameter while creating the connection, the email address associated with that parameter will be used for retrieving email messages.	***@*.*
Exchange Folder Name	Optional	The name of the exchange folder to fetch emails. The available exchange folders are trash, inbox, outbox, sent, junk, drafts, or a customized folder name. If this parameter is not defined, all folders will be returned.	inbox

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "subject": "test attached picture",
        "content": "\r\n",
        "sender": "*****@*****.***",
        "recipients": [
            "*****@*****.***"
        ],
        "datetime_received_utc": "2021-9-24 18:10:9.0",
        "attachmentIDs": [
            "***************************************"
        ],
        "attachmentNames": [
            "2.jpg"
        ],
        "messageId": "<*****@*****.***l>"
    }
]

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

[
    {
        "subject": "test attached picture",
        "content": "\r\n",
        "sender": "*****@*****.***",
        "recipients": [
            "*****@*****.***"
        ],
        "datetime_received_utc": "2021-9-24 18:10:9.0",
        "attachmentIDs": [
            "***************************************"
        ],
        "attachmentNames": [
            "2.jpg"
        ],
        "messageId": "<*****@*****.***l>"
    }
]

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": "\"[\\\"<*****@*****.***l>\\\"]\""
}

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

SUBJECT	CONTENT	SENDER	RECIPIENTS	DATETIME_RECEIVED_UTC	ISREAD	ATTACHMENTIDS	ATTACHMENTNAMES	MESSAGEID
test attached picture		***@****.com	['***@*.*']	2021-9-24 18:10:9:0	False	['***************************************']	['2.jpg']	<***@*.*l>

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 Microsoft Exchange Server integration has some pre-configured field mappings for default field mapping.

Default Event Source
The Default Event Source is the default set of field mappings that are applied when this fetch event command is executed. For out-of-the-box integrations, 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., $) that is used to extract a batch of events from the response raw data. Click Edit Main JSON Path to view the “Main Event JSON Path”.
- Main Event JSON Path: $
  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 $. The child node denoting the Event Key field would be messageId. Putting it together, the JSON Path expression to extract the Event Key is $.messageId.

The pre-configured field mappings are detailed below:

Field Name	Source Field
EmailId	.EmailId
Unique Event Key	.messageId
Start Time	.datetime_received_utc
Email subject	.subject
Sender	.sender
Recipient	.recipient
IsRead	.isRead
AttachmentFileIDs	.attachmentIDs
AttachmentFileNames	.attachmentNames

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 Microsoft Exchange Server 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: Invalid credentials for https://*//**.asmx.

Error Sample Data

Fetch Event failed.

Status Code: 400.

Message: Invalid credentials for https://***/***/***.asmx.

Get Attachment

Retrieves attachments matching the specified criteria.

READER NOTE

Message ID and Attachment ID are required parameters to run this command.

Run the Search All Emails command to obtain Message ID and Attachment ID. Message ID can be found from the returned raw data at the path $[*].messageId; Attachment ID can be found from the returned raw data at the path $[*].attachmentIDs.
Please note that not all messages are guaranteed to have an attachment. To verify if an email has attachments, examine the returned raw data from the Search All Email command.
When inputting the Message ID, ensure the ID is enclosed within "<>" brackets (e.g.<*****@*****.***l>).
The input Message ID and Attachment ID must correspond to each other (i.e. they should be from the same returned raw data object).

Input

Input Parameter	Required /Optional	Description	Example
Message ID	Required	The message ID of the email to retrieve attachments. Message IDs can be obtained using the Search All Emails command. Note: The input message ID must be enclosed within "<>" brackets.	<***@*.*l>
Attachment ID	Required	The ID of the attachment file to retrieve. Attachment IDs can be obtained using the Search All Emails command.	***************************************
Exchange Email	Optional	The email address to retrieve attachments from. Note: If you have specified the "Operational Email" parameter while creating the connection, the email address associated with that parameter will be used for retrieving email attachments.	***@*.*

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

{
    "fileId": "***",
    "fileName": "123.jpg",
    "md5": "***************************************",
    "sha1": "***************************************",
    "sha256": "***************************************"
}

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

FILEID	FILENAME	MD5	SHA1	SHA256
***	66777.png	**************************************	**************************************	**************************************

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 Attachment 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 Microsoft Exchange Server 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: get the email successfully, but the email doesn't have this attachment.

Error Sample Data

Get Attachment failed.

Status Code: 404.

Message: get the email successfully, but the email doesn't have this attachment.

Get Email EMLs

Retrieves emails in EML format and saves it to the D3 database.

READER NOTE

Message ID and Attachment ID are required parameters to run this command.

Run the Search All Emails command to obtain Message ID and Attachment ID. Message ID can be found from the returned raw data at the path $[*].messageId; Attachment ID can be found from the returned raw data at the path $[*].attachmentIDs.
Please note that not all messages are guaranteed to have an attachment. To verify if an email has attachments, examine the returned raw data from the Search All Email command.
When inputting the Message ID, ensure the ID is enclosed within "<>" brackets (e.g.<*****@*****.***l>).
The input Message ID and Attachment ID must correspond to each other (i.e. they should be from the same returned raw data object).

Input

Input Parameter	Required /Optional	Description	Example
Message ID	Required	The message ID of the email to retrieve. Message IDs can be obtained using the Search All Emails command. Note: The input message ID must be enclosed within "<>" brackets.	<***@*.*l>
Attachment ID	Required	The ID of the attachment file to retrieve. Attachment IDs can be obtained using the Search All Emails command.	**************************************
Exchange Email	Optional	The email address to retrieve EML attachments from. Note: If you have specified the "Operational Email" parameter while creating the connection, the email address associated with that parameter will be used for retrieving EML attachments.	***@*.*

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "fileId": "*****",
        "fileName": "****************",
        "md5": "*************",
        "sha1": "***************************************",
        "sha256": "***************************************",
        "originalEmail": [
            {
                "detail": {
                    "attachmentId": "***************************************",
                    "lastModifiedDateTime": "2021-10-01T16:40:00",
                    "name": "test attached picture",
                    "contentType": null,
                    "size": 19196,
                    "isInline": false,
                    "item": {
                        "elementName": "Message",
                        "id": null,
                        "datetimeCreated": "2021-10-01T23:40:00",
                        "datetimeReceived": "2021-09-24T18:10:09",
                        "datetimeSent": "2021-09-24T18:10:09",
                        "lastModifiedDateTime": "2021-10-01T23:40:00",
                        "hasAttachments": true,
                        "messageId": "<*****@*****.***l>",
                        "conversationId": "***************************************",
                        "conversationIndex": "***************************************",
                        "isReadReceiptRequested": false,
                        "isRead": true,
                        "isDraft": false,
                        "internetMessageHeaders": [
                            {
                                "name": "Received",
                                "value": "from ***.***.*** (***.***.***.***) by ***.***.*** (***.***.***.***) with Microsoft SMTP Server (version=***, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id *.*.*.* via Mailbox Transport; Fri, 24 Sep 2021 11:10:09 -0700"
                            },
                            {
                                "name": "Received",
                                "value": "from ***.***.*** (***.***.***.***) by ***.***.*** (***.***.***.***) with Microsoft SMTP Server (version=***, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id *.*.*.*; Fri, 24 Sep 2021 11:10:09 -0700"
                            },
                            {
                                "name": "Received",
                                "value": "from ***.***.*** ([****::****:****:****:****]) by ***.***.*** ([****::****:****:****:****]) with mapi id ***.***.***; Fri, 24 Sep 2021 11:10:09 -0700"
                            },
                            {
                                "name": "Content-Type",
                                "value": "application/ms-tnef"
                            },
                            {
                                "name": "Content-Transfer-Encoding",
                                "value": "binary"
                            },
                            {
                                "name": "Subject",
                                "value": "test attached picture"
                            },
                            {
                                "name": "Thread-Topic",
                                "value": "test attached picture"
                            },
                            {
                                "name": "Thread-Index",
                                "value": "***************************************"
                            },
                            {
                                "name": "Date",
                                "value": "Fri, 24 Sep 2021 11:10:09 -0700"
                            },
                            {
                                "name": "Message-ID",
                                "value": "<*****@*****.***l>"
                            },
                            {
                                "name": "Accept-Language",
                                "value": "en-US"
                            },
                            {
                                "name": "Content-Language",
                                "value": "en-US"
                            },
                            {
                                "name": "X-MS-Has-Attach",
                                "value": "yes"
                            },
                            {
                                "name": "X-MS-Exchange-Organization-SCL",
                                "value": "-1"
                            },
                            {
                                "name": "X-MS-TNEF-Correlator",
                                "value": "<*****@*****.***l>"
                            },
                            {
                                "name": "MIME-Version",
                                "value": "*.*"
                            },
                            {
                                "name": "X-MS-Exchange-Organization-MessageDirectionality",
                                "value": "Originating"
                            },
                            {
                                "name": "X-MS-Exchange-Organization-AuthSource",
                                "value": "***.***.***"
                            },
                            {
                                "name": "X-MS-Exchange-Organization-AuthAs",
                                "value": "Internal"
                            },
                            {
                                "name": "X-MS-Exchange-Organization-AuthMechanism",
                                "value": "04"
                            },
                            {
                                "name": "X-Originating-IP",
                                "value": "[***.***.***.***]"
                            },
                            {
                                "name": "X-MS-Exchange-Organization-Network-Message-Id",
                                "value": "***************************************"
                            },
                            {
                                "name": "Return-Path",
                                "value": "*****@******.com"
                            },
                            {
                                "name": "X-MS-Exchange-Organization-AVStamp-Enterprise",
                                "value": "*.*"
                            },
                            {
                                "name": "X-MS-Exchange-Transport-EndToEndLatency",
                                "value": "**:**:**.*****"
                            },
                            {
                                "name": "X-MS-Exchange-Processed-By-BccFoldering",
                                "value": "***.***.***.***"
                            }
                        ],
                        "body": "\r\n\r\n<!-- P {margin-top:0;margin-bottom:0;} -->\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n",
                        "sender": {
                            "emailAddress": {
                                "name": "*****",
                                "address": "*****@******.com"
                            }
                        },
                        "toRecipients": [
                            {
                                "emailAddress": {
                                    "name": "*****",
                                    "address": "*****@*****.***"
                                }
                            }
                        ],
                        "ccRecipients": null,
                        "bccRecipients": null
                    }
                }
            }
        ]
    }
]

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

[
    {
        "fileId": "*****",
        "fileName": "****************",
        "md5": "*************",
        "sha1": "***************************************",
        "sha256": "***************************************",
        "originalEmail": [
            {
                "detail": {
                    "attachmentId": "***************************************",
                    "lastModifiedDateTime": "2021-10-01T16:40:00",
                    "name": "test attached picture",
                    "contentType": null,
                    "size": 19196,
                    "isInline": false,
                    "item": {
                        "elementName": "Message",
                        "id": null,
                        "datetimeCreated": "2021-10-01T23:40:00",
                        "datetimeReceived": "2021-09-24T18:10:09",
                        "datetimeSent": "2021-09-24T18:10:09",
                        "lastModifiedDateTime": "2021-10-01T23:40:00",
                        "hasAttachments": true,
                        "messageId": "<*****@*****.***l>",
                        "conversationId": "***************************************",
                        "conversationIndex": "***************************************",
                        "isReadReceiptRequested": false,
                        "isRead": true,
                        "isDraft": false,
                        "internetMessageHeaders": [
                            {
                                "name": "Received",
                                "value": "from ***.***.*** (***.***.***.***) by ***.***.*** (***.***.***.***) with Microsoft SMTP Server (version=***, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id *.*.*.* via Mailbox Transport; Fri, 24 Sep 2021 11:10:09 -0700"
                            },
                            {
                                "name": "Received",
                                "value": "from ***.***.*** (***.***.***.***) by ***.***.*** (***.***.***.***) with Microsoft SMTP Server (version=***, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id *.*.*.*; Fri, 24 Sep 2021 11:10:09 -0700"
                            },
                            {
                                "name": "Received",
                                "value": "from ***.***.*** ([****::****:****:****:****]) by ***.***.*** ([****::****:****:****:****]) with mapi id ***.***.***; Fri, 24 Sep 2021 11:10:09 -0700"
                            },
                            {
                                "name": "Content-Type",
                                "value": "application/ms-tnef"
                            },
                            {
                                "name": "Content-Transfer-Encoding",
                                "value": "binary"
                            },
                            {
                                "name": "Subject",
                                "value": "test attached picture"
                            },
                            {
                                "name": "Thread-Topic",
                                "value": "test attached picture"
                            },
                            {
                                "name": "Thread-Index",
                                "value": "******************"
                            },
                            {
                                "name": "Date",
                                "value": "Fri, 24 Sep 2021 11:10:09 -0700"
                            },
                            {
                                "name": "Message-ID",
                                "value": "<*****@*****.***l>"
                            },
                            {
                                "name": "Accept-Language",
                                "value": "en-US"
                            },
                            {
                                "name": "Content-Language",
                                "value": "en-US"
                            },
                            {
                                "name": "X-MS-Has-Attach",
                                "value": "yes"
                            },
                            {
                                "name": "X-MS-Exchange-Organization-SCL",
                                "value": "-1"
                            },
                            {
                                "name": "X-MS-TNEF-Correlator",
                                "value": "<*****@*****.***l>"
                            },
                            {
                                "name": "MIME-Version",
                                "value": "*.*"
                            },
                            {
                                "name": "X-MS-Exchange-Organization-MessageDirectionality",
                                "value": "Originating"
                            },
                            {
                                "name": "X-MS-Exchange-Organization-AuthSource",
                                "value": "***.***.***"
                            },
                            {
                                "name": "X-MS-Exchange-Organization-AuthAs",
                                "value": "Internal"
                            },
                            {
                                "name": "X-MS-Exchange-Organization-AuthMechanism",
                                "value": "04"
                            },
                            {
                                "name": "X-Originating-IP",
                                "value": "[***.***.***.***]"
                            },
                            {
                                "name": "X-MS-Exchange-Organization-Network-Message-Id",
                                "value": "***************************************"
                            },
                            {
                                "name": "Return-Path",
                                "value": "*****@******.com"
                            },
                            {
                                "name": "X-MS-Exchange-Organization-AVStamp-Enterprise",
                                "value": "*.*"
                            },
                            {
                                "name": "X-MS-Exchange-Transport-EndToEndLatency",
                                "value": "**:**:**.*****"
                            },
                            {
                                "name": "X-MS-Exchange-Processed-By-BccFoldering",
                                "value": "***.***.***.***"
                            }
                        ],
                        "body": "\r\n\r\n<!-- P {margin-top:0;margin-bottom:0;} -->\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n\r\n",
                        "sender": {
                            "emailAddress": {
                                "name": "*****",
                                "address": "*****@******.com"
                            }
                        },
                        "toRecipients": [
                            {
                                "emailAddress": {
                                    "name": "*****",
                                    "address": "*****@*****.***"
                                }
                            }
                        ],
                        "ccRecipients": null,
                        "bccRecipients": null
                    }
                }
            }
        ]
    }
]

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

FILEID

FILENAME

MD5

SHA1

SHA256

ORIGINALEMAIL

351

****************

******************************

[{'detail': {'attachmentId': '***************************************', 'lastModifiedDateTime': '2021-10-01T16:40:00', 'name': 'test attached picture', 'contentType': None, 'size': 19196, 'isInline': False, 'item': {'elementName': 'Message', 'id': None, 'datetimeCreated': '2021-10-01T23:40:00', 'datetimeReceived': '2021-09-24T18:10:09', 'datetimeSent': '2021-09-24T18:10:09', 'lastModifiedDateTime': '2021-10-01T23:40:00', 'hasAttachments': True, 'messageId': '<*****@*****.***l>', 'conversationId': '***************************************', 'conversationIndex': '***************************************', 'isReadReceiptRequested': False, 'isRead': True, 'isDraft': False, 'internetMessageHeaders': [{'name': 'Received', 'value': 'from ***.***.*** (***.***.***.***) by ***.***.*** (***.***.***.***) with Microsoft SMTP Server (version=***, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id *.*.*.* via Mailbox Transport; Fri, 24 Sep 2021 11:10:09 -0700'}, {'name': 'Received', 'value': 'from ***.***.*** (***.***.***.***) by ***.***.*** (***.***.***.***) with Microsoft SMTP Server (version=***, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id *.*.*.*; Fri, 24 Sep 2021 11:10:09 -0700'}, {'name': 'Received', 'value': 'from ***.***.*** ([****::****:****:****:****]) by ***.***.*** ([****::****:****:****:****]) with mapi id ***.***.***; Fri, 24 Sep 2021 11:10:09 -0700'}, {'name': 'Content-Type', 'value': 'application/ms-tnef'}, {'name': 'Content-Transfer-Encoding', 'value': 'binary'}, {'name': 'Subject', 'value': 'test attached picture'}, {'name': 'Thread-Topic', 'value': 'test attached picture'}, {'name': 'Thread-Index', 'value': '***************************************'}, {'name': 'Date', 'value': 'Fri, 24 Sep 2021 11:10:09 -0700'}, {'name': 'Message-ID', 'value': '<*****@*****.***l>'}, {'name': 'Accept-Language', 'value': 'en-US'}, {'name': 'Content-Language', 'value': 'en-US'}, {'name': 'X-MS-Has-Attach', 'value': 'yes'}, {'name': 'X-MS-Exchange-Organization-SCL', 'value': '-1'}, {'name': 'X-MS-TNEF-Correlator', 'value': '<*****@*****.***l>'}, {'name': 'MIME-Version', 'value': '*.*'}, {'name': 'X-MS-Exchange-Organization-MessageDirectionality', 'value': 'Originating'}, {'name': 'X-MS-Exchange-Organization-AuthSource', 'value': '***.***.***'}, {'name': 'X-MS-Exchange-Organization-AuthAs', 'value': 'Internal'}, {'name': 'X-MS-Exchange-Organization-AuthMechanism', 'value': '04'}, {'name': 'X-Originating-IP', 'value': '[***.***.***.***]'}, {'name': 'X-MS-Exchange-Organization-Network-Message-Id', 'value': '***************************************'}, {'name': 'Return-Path', 'value': '*****@******.com'}, {'name': 'X-MS-Exchange-Organization-AVStamp-Enterprise', 'value': '*.*'}, {'name': 'X-MS-Exchange-Transport-EndToEndLatency', 'value': '**:**:**.*****'}, {'name': 'X-MS-Exchange-Processed-By-BccFoldering', 'value': '***.***.***.***'}], 'body': '\\r\\n\\r\\n\\r\\n\\r\\n\\r\\n

\\r\\n

\\r\\n\\r\\n\\r\\n', 'sender': {'emailAddress': {'name': '*****', 'address': '*****@******.com'}}, 'toRecipients': [{'emailAddress': {'name': 'Administrator', 'address': '*****@*****.***'}}], 'ccRecipients': None, 'bccRecipients': None}}}]

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 Microsoft Exchange Server 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: get the email successfully, but the email doesn't have this attachment.

Error Sample Data

Get Email EMLs failed.

Status Code: 404.

Message: get the email successfully, but the email doesn't have this attachment.

Get EML Attachments

Retrieves the attachments associated with the provided Message ID and EML attachment IDs, and saves them to the D3 database.

READER NOTE

Message ID and Attachment ID are required parameters to run this command.

Run the Search All Emails command to obtain Message ID and Attachment ID. Message ID can be found from the returned raw data at the path $[*].messageId; Attachment ID can be found from the returned raw data at the path $[*].attachmentIDs.
Please note that not all messages are guaranteed to have an attachment. To verify if an email has attachments, examine the returned raw data from the Search All Email command.
When inputting the Message ID, ensure the ID is enclosed within "<>" brackets (e.g.<*****@*****.***l>).
The input Message ID and Attachment ID must correspond to each other (i.e. they should be from the same returned raw data object).

Input

Input Parameter	Required /Optional	Description	Example
Message ID	Required	The message ID of the email to retrieve EML attachments. Message IDs can be obtained using the Search All Email command. Note: The input message ID must be enclosed within "<>" brackets.	<***@***.com>
Attachment IDs	Required	The ID of the attachment file to retrieve. Attachment IDs can be obtained using the Search All Email command.	["***************************************"]
Exchange Email	Optional	The email address to retrieve EML attachments from. Note: If you have specified the "Operational Email" parameter while creating the connection, the email address associated with that parameter will be used for retrieving EML attachments.	***@*.*

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "originalEmail": [
            {
                "detail": {
                    "attachmentId": "***************************************",
                    "lastModifiedDateTime": "2021-10-27T15:56:13",
                    "name": "okok",
                    "contentType": null,
                    "size": 238455,
                    "isInline": false,
                    "item": {
                        "elementName": "Message",
                        "id": null,
                        "datetimeCreated": "2021-10-27T22:57:35",
                        "datetimeReceived": "2021-07-26T18:30:28",
                        "datetimeSent": "2021-07-26T18:30:04",
                        "lastModifiedDateTime": "2021-10-27T22:57:15",
                        "hasAttachments": true,
                        "messageId": "",
                        "conversationId": "***************************************",
                        "conversationIndex": "***************************************",
                        "isReadReceiptRequested": false,
                        "isRead": true,
                        "isDraft": false,
                        "internetMessageHeaders": [
                            {
                                "name": "Received",
                                "value": "from ***.***.*** (***.***.***.***) by ***.***.*** (***.***.***.***) with Microsoft SMTP Server (version=***, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id *.*.*.* via Mailbox Transport; Mon, 26 Jul 2021 11:30:20 -0700"
                            },
                            {
                                "name": "Received",
                                "value": "from ***.***.*** (***.***.***.***) by ***.***.*** (***.***.***.***) with Microsoft SMTP Server (version=***, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id *.*.*.*; Mon, 26 Jul 2021 11:30:09 -0700"
                            },
                            {
                                "name": "Received",
                                "value": "from ***.***.*** ([****::****:****:****:****]) by ***.***.*** ([****::****:****:****:****]) with mapi id 15.01.1713.004; Mon, 26 Jul 2021 11:30:08 -0700"
                            },
                            {
                                "name": "Content-Type",
                                "value": "application/ms-tnef"
                            },
                            {
                                "name": "Content-Transfer-Encoding",
                                "value": "binary"
                            },
                            {
                                "name": "Subject",
                                "value": "okok"
                            },
                            {
                                "name": "Thread-Topic",
                                "value": "okok"
                            },
                            {
                                "name": "Thread-Index",
                                "value": "***************************************"
                            },
                            {
                                "name": "Date",
                                "value": "Mon, 26 Jul 2021 11:30:04 -0700"
                            },
                            {
                                "name": "Message-ID",
                                "value": ""
                            },
                            {
                                "name": "Accept-Language",
                                "value": "en-US"
                            },
                            {
                                "name": "Content-Language",
                                "value": "en-US"
                            },
                            {
                                "name": "X-MS-Has-Attach",
                                "value": "yes"
                            },
                            {
                                "name": "X-MS-Exchange-Organization-SCL",
                                "value": "-1"
                            },
                            {
                                "name": "X-MS-TNEF-Correlator",
                                "value": ""
                            },
                            {
                                "name": "MIME-Version",
                                "value": "*.*"
                            },
                            {
                                "name": "X-MS-Exchange-Organization-MessageDirectionality",
                                "value": "Originating"
                            },
                            {
                                "name": "X-MS-Exchange-Organization-AuthSource",
                                "value": "***.***.***"
                            },
                            {
                                "name": "X-MS-Exchange-Organization-AuthAs",
                                "value": "Internal"
                            },
                            {
                                "name": "X-MS-Exchange-Organization-AuthMechanism",
                                "value": "04"
                            },
                            {
                                "name": "X-Originating-IP",
                                "value": "[***.***.***.***]"
                            },
                            {
                                "name": "X-MS-Exchange-Organization-Network-Message-Id",
                                "value": "***************************************"
                            },
                            {
                                "name": "Return-Path",
                                "value": "*****@*****.***"
                            },
                            {
                                "name": "X-MS-Exchange-Organization-AVStamp-Enterprise",
                                "value": "*.*"
                            },
                            {
                                "name": "X-MS-Exchange-Transport-EndToEndLatency",
                                "value": "00:00:16.4222999"
                            },
                            {
                                "name": "X-MS-Exchange-Processed-By-BccFoldering",
                                "value": "***.***.***.***"
                            }
                        ],
                        "body": "\r\n\r\n<!-- P {margin-top:0;margin-bottom:0;} -->\r\n\r\n\r\n\r\nattachment\r\n\r\n\r\n\r\n",
                        "sender": {
                            "emailAddress": {
                                "name": "*****",
                                "address": "*****@*****.***"
                            }
                        },
                        "toRecipients": [
                            {
                                "emailAddress": {
                                    "name": "*****",
                                    "address": "*****@*****.***"
                                }
                            }
                        ],
                        "ccRecipients": [
                            {
                                "emailAddress": {
                                    "name": "*****",
                                    "address": "*****@******.com"
                                }
                            }
                        ],
                        "bccRecipients": null
                    }
                }
            }
        ]
    }
]

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

[
    {
        "originalEmail": [
            {
                "detail": {
                    "attachmentId": "***************************************",
                    "lastModifiedDateTime": "2021-10-27T15:56:13",
                    "name": "okok",
                    "contentType": null,
                    "size": 238455,
                    "isInline": false,
                    "item": {
                        "elementName": "Message",
                        "id": null,
                        "datetimeCreated": "2021-10-27T22:57:35",
                        "datetimeReceived": "2021-07-26T18:30:28",
                        "datetimeSent": "2021-07-26T18:30:04",
                        "lastModifiedDateTime": "2021-10-27T22:57:15",
                        "hasAttachments": true,
                        "messageId": "",
                        "conversationId": "***************************************",
                        "conversationIndex": "***************************************",
                        "isReadReceiptRequested": false,
                        "isRead": true,
                        "isDraft": false,
                        "internetMessageHeaders": [
                            {
                                "name": "Received",
                                "value": "from ***.***.*** (***.***.***.***) by ***.***.*** (***.***.***.***) with Microsoft SMTP Server (version=***, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id *.*.*.* via Mailbox Transport; Mon, 26 Jul 2021 11:30:20 -0700"
                            },
                            {
                                "name": "Received",
                                "value": "from ***.***.*** (***.***.***.***) by ***.***.*** (***.***.***.***) with Microsoft SMTP Server (version=***, cipher=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256) id *.*.*.*; Mon, 26 Jul 2021 11:30:09 -0700"
                            },
                            {
                                "name": "Received",
                                "value": "from ***.***.*** ([****::****:****:****:****]) by ***.***.*** ([****::****:****:****:****]) with mapi id 15.01.1713.004; Mon, 26 Jul 2021 11:30:08 -0700"
                            },
                            {
                                "name": "Content-Type",
                                "value": "application/ms-tnef"
                            },
                            {
                                "name": "Content-Transfer-Encoding",
                                "value": "binary"
                            },
                            {
                                "name": "Subject",
                                "value": "okok"
                            },
                            {
                                "name": "Thread-Topic",
                                "value": "okok"
                            },
                            {
                                "name": "Thread-Index",
                                "value": "***************************************"
                            },
                            {
                                "name": "Date",
                                "value": "Mon, 26 Jul 2021 11:30:04 -0700"
                            },
                            {
                                "name": "Message-ID",
                                "value": ""
                            },
                            {
                                "name": "Accept-Language",
                                "value": "en-US"
                            },
                            {
                                "name": "Content-Language",
                                "value": "en-US"
                            },
                            {
                                "name": "X-MS-Has-Attach",
                                "value": "yes"
                            },
                            {
                                "name": "X-MS-Exchange-Organization-SCL",
                                "value": "-1"
                            },
                            {
                                "name": "X-MS-TNEF-Correlator",
                                "value": ""
                            },
                            {
                                "name": "MIME-Version",
                                "value": "*.*"
                            },
                            {
                                "name": "X-MS-Exchange-Organization-MessageDirectionality",
                                "value": "Originating"
                            },
                            {
                                "name": "X-MS-Exchange-Organization-AuthSource",
                                "value": "***.***.***"
                            },
                            {
                                "name": "X-MS-Exchange-Organization-AuthAs",
                                "value": "Internal"
                            },
                            {
                                "name": "X-MS-Exchange-Organization-AuthMechanism",
                                "value": "04"
                            },
                            {
                                "name": "X-Originating-IP",
                                "value": "[***.***.***.***]"
                            },
                            {
                                "name": "X-MS-Exchange-Organization-Network-Message-Id",
                                "value": "***************************************"
                            },
                            {
                                "name": "Return-Path",
                                "value": "*****@*****.***"
                            },
                            {
                                "name": "X-MS-Exchange-Organization-AVStamp-Enterprise",
                                "value": "*.*"
                            },
                            {
                                "name": "X-MS-Exchange-Transport-EndToEndLatency",
                                "value": "00:00:16.4222999"
                            },
                            {
                                "name": "X-MS-Exchange-Processed-By-BccFoldering",
                                "value": "***.***.***.***"
                            }
                        ],
                        "body": "\r\n\r\n<!-- P {margin-top:0;margin-bottom:0;} -->\r\n\r\n\r\n\r\nattachment\r\n\r\n\r\n\r\n",
                        "sender": {
                            "emailAddress": {
                                "name": "*****",
                                "address": "*****@*****.***"
                            }
                        },
                        "toRecipients": [
                            {
                                "emailAddress": {
                                    "name": "*****",
                                    "address": "*****@*****.***"
                                }
                            }
                        ],
                        "ccRecipients": [
                            {
                                "emailAddress": {
                                    "name": "*****",
                                    "address": "*****@******.com"
                                }
                            }
                        ],
                        "bccRecipients": null
                    }
                }
            }
        ]
    }
]

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

FILE NAME	MD5 HASH	SHA1 HASH	SHA256 HASH
okok.eml	***********************	***********************	***********************

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 EML 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 Microsoft Exchange Server 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: get the Email and attached Email TYPE attachments successfully, but the attached emails don't have any attachment(s).

Error Sample Data

Get EML Attachments failed.

Status Code: 404.

Message: get the Email and attached Email TYPE attachments successfully, but the attached emails don't have any attachment(s).

Remove Emails

Deletes emails matching the specified criteria.

READER NOTE

The parameter Message IDs is optional to run this command.
- Run the Search All Emails command to obtain Message IDs. Message IDs can be found from the returned raw data at the path $[*].messageId.
At least one parameter must be defined for the command to run successfully.
A previously deleted email cannot be removed again.

Input

Input Parameter	Required /Optional	Description	Example
Subject	Optional	The email subject to filter emails to remove.	attached
Content	Optional	The email message content to filter emails to remove.	search mail test1
Attachment Name	Optional	The attachment name to filter emails to remove.	.jpg
Sender Mail Address	Optional	The full sender email address to filter emails to remove.	***@*.*
Message IDs	Optional	The message IDs to filter emails to delete. Message IDs can be obtained using the Search All Emails command. Note: The input message IDs must be enclosed within "<>" brackets.	["<***@*.*l>"]
Exchange Email	Optional	The email address from which to remove emails. Note: If you have specified the "Operational Email" parameter while creating the connection, the email address associated with that parameter will be used for removing emails.	***@*.*

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "subject": "test attached picture",
        "content": "\\r\\n",
        "sender": "*****@******.com",
        "recipients": [
            "*****@*****.***"
        ],
        "datetime_received_utc": "2021-9-24 18:10:9:0",
        "status": "deleted item",
        "messageId": "<*****@*****.***l>",
        "isRead": false
    }
]

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

[
    {
        "subject": "test attached picture",
        "content": "\\r\\n",
        "sender": "*****@******.com",
        "recipients": [
            "*****@*****.***"
        ],
        "datetime_received_utc": "2021-9-24 18:10:9:0",
        "status": "deleted item",
        "messageId": "<*****@*****.***l>",
        "isRead": false
    }
]

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

SUBJECT	CONTENT	SENDER	RECIPIENTS	DATETIME_RECEIVED_UTC	ATTACHMENTIDS	ATTACHMENTNAMES	STATUS	MESSAGEID	ISREAD
Teng Test 2021-10-01	This is a Test, Hello The World!!	***@*.*	['***@*.*']	2021-10-1 18:5:28:0	[]	[]	deleted item	<***@*.*>	True

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 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 Microsoft Exchange Server 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: find the email by the messageId failed.

Error Sample Data

Remove Emails failed.

Status Code: 404.

Message: find the email by the messageId failed.

Search All Emails

Searches and returns the latest emails in all mailboxes using the given search criteria.

READER NOTE

Invalid filters will result in the command running successfully with no results.

Input

Input Parameter	Required /Optional	Description	Example
Subject	Optional	The email subject to filter returned emails.	attached
Content	Optional	The email message content to filter returned emails.	search mail test1
Attachment Name	Optional	The attachment name to filter returned emails.	.jpg
Sender Mail Address	Optional	The full sender email address to filter returned emails.	***@*.*
Limit	Optional	The maximum number of emails to retrieve from each accessible mailbox if the parameter Exchange Email is not defined. The number of returned records may exceed the default or specified input value. The default value is 20.	1
Exchange Folder Name	Optional	The name of the exchange folder to fetch emails. The available exchange folders are trash, inbox, outbox, sent, junk, drafts, or a customized folder name. If this parameter is not defined, all folders will be returned.	inbox,junk
Exchange Email	Optional	The email address to retrieve email messages from. Note: If you have specified the "Operational Email" parameter while creating the connection, the email address associated with that parameter will be used for retrieving email messages.	***@*.*

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON

[
    {
        "subject": "test attached picture",
        "content": "\r\n",
        "sender": "*****@*****.***",
        "recipients": [
            "*****@*****.***"
        ],
        "datetime_received_utc": "2021-9-24 18:10:9.0",
        "attachmentIDs": [
            "***************************************"
        ],
        "attachmentNames": [
            "2.jpg"
        ],
        "messageId": "<*****@*****.***l>",
        "isRead": false
    }
]

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

[
    {
        "subject": "test attached picture",
        "content": "\r\n",
        "sender": "*****@*****.***",
        "recipients": [
            "*****@*****.***"
        ],
        "datetime_received_utc": "2021-9-24 18:10:9.0",
        "attachmentIDs": [
            "***************************************"
        ],
        "attachmentNames": [
            "2.jpg"
        ],
        "messageId": "<*****@*****.***l>",
        "isRead": false
    }
]

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": "\"[\\\"<*****@*****.***l>\\\"]\""
}

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

SUBJECT	CONTENT	SENDER	RECIPIENTS	DATETIME_RECEIVED_UTC	ATTACHMENTIDS	ATTACHMENTNAMES	MESSAGEID	ISREAD
test attached picture		***@****.com	['***@*.*']	2021-9-24 18:10:9:0	['***************************************']	['2.jpg']	<***@*.*l>	False
okok	attachment	***@*.*	['***@*.*']	2021-7-26 18:30:28:0	['***********************']	['66777.png']		True

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 All 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 Microsoft Exchange Server 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: Invalid credentials for https://*//**.asmx.

Error Sample Data

Search All Emails failed.

Status Code: 400.

Message: Invalid credentials for https://***/***/***.asmx.

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 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.	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 Microsoft Exchange Server 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: Invalid credentials for https://*//**.asmx.

Error Sample Data

Test Connection failed. Failed to check the connector.

Status Code: 400.

Message: Invalid credentials for https://***/***/***.asmx.