Skip to main content
Skip table of contents

Gmail V2

LAST UPDATED: 02/13/2024

Overview

The Gmail API is used to interact with users' Gmail inboxes and settings such as sending emails, searching emails, modifying email labels, creating users, setting user passwords, setting auto-replies, etc.

D3 SOAR is providing REST operations to function with Gmail.

Gmail V2 is available for use in:

D3 SOAR

V15.0+

Category

Email Messaging

Deployment Options

Option II, Option IV

Known Limitations

The Gmail API is subject to a daily usage limit that applies to all requests made from the application, and per-user rate limits. Each limit is identified in terms of quota units, or an abstract unit of measurement representing Gmail resource usage. The following table details the main request limits:

Please refer to Gmail API Usage Limits for detailed information.

Connection

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

Parameter

Description

Example

Default

Authentication Type

The authentication method (i.e., Service Account or OAuth Client ID) to use for the connection.

If you want to impersonate another account, you should choose the Service Account authentication type. If you select the OAuth Client ID authentication type, you can only access the data of the user who consented your access.

Service Account

API Version

The version of the API to use for the connection.

v1

OAuth Client ID

Client ID

The client ID to authenticate the API connection.

1067****8962-qp8f************************fsqm.apps.googleusercontent.com

Client Secret

The client secret to authenticate the API connection.

GOCSPX-e9hi********************ejaY

Authorization Code

The authorization code for OAuth Client ID authentication. Click the "Get Authorization" button on the Connection page to automatically generate an authorization code.

4/0888-w

Callback URL

The callback URL for OAuth Client ID authentication. Please add this callback url on Google Cloud console according to the instructions.

https://***/VSOC/Auth2Callback.aspx

Refresh Token

The refresh token for the OAuth Client ID authentication. Click the "Get Refresh Token" button on the Connection page to automatically generate a refresh token. This parameter is read-only and Auto-generated.

1//****************

Service Account

Admin Email

The admin user email for authentication. If you want to run Directory User related commands, such as Create User, Delete User, Get User List, Set User Password etc., this account must have admin permissions.

test@example.com

Service Account JSON

The content of the service account JSON file.

{

"type": "service_account",

"project_id": "nimble-cortex-2****8",

"private_key_id": "69ba*********************************59ae",

"private_key": "-----BEGIN PRIVATE KEY-----\n*******************************************g==\n-----END PRIVATE KEY-----\n",

"client_email": "gke-519@nimble-cortex-2****8.iam.gserviceaccount.com",

"client_id": "1004*************4677",

"auth_uri": "https://accounts.google.com/o/oauth2/auth",

"token_uri": "https://oauth2.googleapis.com/token",

"auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",

"client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/gke-519%40nimble-cortex-2****8.iam.gserviceaccount.com"

}

Permission Requirements

Each endpoint in the Gmail V2 API requires a certain permission scope. The following are required scopes for the commands in this integration for both authentication methods:

  • https://www.googleapis.com/auth/admin.directory.user

  • https://mail.google.com/

  • https://www.googleapis.com/auth/gmail.settings.sharing

  • https://www.googleapis.com/auth/gmail.settings.basic

Please note these scopes must be set up in various locations for two different authentication methods. Refer to the corresponding sections below for detailed setup instructions.

Configuring Gmail V2 to Work with D3 SOAR

For each Authentication Type, different configuration steps are required. Refer to the corresponding sections for details following details.

Service Account

Creating Service Account and Obtaining the Service Account JSON

  1. To connect Google Kubernetes Engine with D3 SOAR, we need to configure the Service Account JSON file. First, log in to the Google Cloud Platform(GCP) console with admin credentials.

  2. Click the Hamburger Menu in the top left corner to reveal the sidebar menu. Navigate to APIs and services. In its submenu, select Credentials.

  3. Click + CREATE CREDENTIALS, and select Service account.

  4. Input the Service account name and description, and click CREATE AND CONTINUE.

  5. (Optional) Assign a role to the service account (e.g. owner), then click CONTINUE.

  6. You can opt to grant users access to this service account. Click DONE to confirm your configurations.

  7. You will find the service account you have just created on the credentials page. Click and open the service account.

  8. In the KEYS tab, click ADD KEY, then select Create new key.

  9. Choose JSON as the key type, then click CREATE.

  10. The Service Account JSON file (Private key) will automatically be downloaded to your computer.

  11. If it is your first time using Google Calendar API, you need to enable it. From the GCP portal Navigation menu, click API and services, then click Library.

  12. Search for Gmail.

  13. Click ENABLE. A green check mark and notice showing "API Enabled" will appear to the right of the button upon successful enablement.

Configuring the Service Account Domain-wide Delegation

You will also need to enable the Google Workspace domain-wide delegation for your created service account. Please follow the steps below.

  1. Log in to the Google Workspace Admin Console with admin credentials. Click Security > Access and data control > API controls. Scroll down and click MANAGE DOMAIN-WIDE DELEGATION.

  2. Click Add new to add a new API client.

  3. Find your Client ID in the service account you created and paste it into the Client ID field. Input the following scopes into the OAuth scopes field:

  4. The service account domain-wide delegation can now be found on the API controls page. Your created service account is now ready to use.

OAuth Client ID

Assigning Scope to Target Project

Refer to Configure the OAuth consent screen and choose scopes from Google's documentation for instructions.

Creating a Client ID and Secret

Ensure your project has the appropriate scope for the OAuth credentials. The client ID you create will depend on this scope.

  1. Log in to the Google Cloud console with your admin account.

  2. Navigate to APIs and services > Credentials > Create credentials > OAuth client ID.

  3. Select Web Application for Authentication type.

  4. Enter a name for your OAuth client. Next, paste the callback URL you obtained from the D3 SOAR connection page into the Authorized Redirect URIs field. Finally, click CREATE to save the configuration.

  5. Copy and save the Client ID and Client Secret in a secure location. It will be required for setting up the integration connection in D3 SOAR.

Assigning a User Management Role for a Google Account

To utilize OAuth connectors, it is required to enable the User Management role on your Gmail account.

  1. Access the Google Admin, navigate to Directory > Users, and select the account you are configuring for OAuth credentials.

  2. Scroll to the Roles section and assign the User Management admin role to this user.

  3. Enable the User Management role. Your user account is now ready and can be utilized for OAuth authentication to establish a connection in D3 SOAR.

Configure Gmail Integration on D3 SOAR

  1. Log in to D3 SOAR.

  2. Find the Gmail V2 integration.

    1. Navigate to Configuration on the top header menu.

    2. Click on the Integration icon on the left sidebar.

    3. Type Gmail V2 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.

  3. Configure the following fields to create a connection to Gmail V2.

    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.
      [IMAGE]

    9. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
      Authentication Type: Service Account

      1. Select Basic Authentication.

      2. Input the Admin Email used to log in to Google Cloud Platform (GCP) console.

      3. Input your Service Account JSON File.

      4. Input the API version to use for the connection. The default API version is v1.
      Authentication Type: OAuth Client ID

      1. Select OAuth Client ID.

      2. Input your saved Client ID.

      3. Input your saved Client Secret.

      4. Click Get Authorization. You will then need to sign in to your Google Account. Following this, grant D3 SOAR permission to access your Google account by clicking on Allow.

      You will be redirected to a page with your Authorization Code. Copy and paste it into the Authorization Code parameter.

      5. Input the API version to use for the connection. The default API version is v1.
      Note: No action is required for the Refresh Token command.

    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.

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

Gmail V2 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 Gmail V2 API, please refer to the Gmail V2 API reference.

Reader Note

Certain permissions are required for each command. Please refer to the Permission Requirements and Configuring Gmail V2 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:

  1. Navigate to Configuration > Application Settings. Select Date/Time Format.

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

Create User

Creates a user based on the provided information. Note: If your connection uses OAuth Client ID authentication, the authenticated Google account must possess user management permissions.

Reader Note

  • The email address you create must belong to the specified domain. Any email address outside this domain will result in a 403 Forbidden error, indicating unauthorized access. Your domain can be found on the Welcome page upon login, as shown in the example below.

Input

Input Parameter

Required/Optional

Description

Example

Family Name

Required

The last name of the user.

McDonald

Given Name

Required

The first name of the user.

Mike

Password

Required

The password for the user account.

ChangeMe!

User Email

Required

The email address of the user.

test@example.com

Custom Fields

Optional

The JSON array containing the additional key-value pairs to enter for the user account.

{

"phones": [

{

"value": "+1 604 123 4567",

"type": "work"

}

],

"changePasswordAtNextLogin": true

}

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON 
{
    "kind": "admin#directory#user",
    "id": "***",
    "etag": "\"***-**/***\"",
    "primaryEmail": "test@example.com",
    "name": {
        "givenName": "Mike",
        "familyName": "McDonald"
    },
    "isAdmin": false,
    "isDelegatedAdmin": false,
    "creationTime": "2022-05-17T19:44:35.000Z",
    "changePasswordAtNextLogin": true,
    "phones": [
        {
            "value": "+1 604 123 4567",
            "type": "work"
        }
    ],
    "customerId": "***",
    "orgUnitPath": "/",
    "isMailboxSetup": 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

JSON 
{
  "userID": "***"
}
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.

Create User 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 Gmail V2 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: Not Authorized to access this resource/api.

Error Sample Data

Create User failed.

Status Code: 403.

Message: Not Authorized to access this resource/api.

Delete Emails

Immediately and permanently deletes the specified emails. This operation cannot be undone. Use the Trash Emails command instead to move emails to the trash. Note: if using the OAuth Client ID authentication type to authenticate the integration connection, you can only delete emails of the google accounts who consent to your access.

Reader Note

Input parameter User Email and Message IDs are required to run this command.

  • Run the Get User List command to obtain User Email. User Emails can be found from the returned raw data at the path $.users[*].primaryEmail.

  • Run the Search Emails command to obtain Message IDs. Message IDs can be found from the returned raw data at the path $.messages[*].id.

  • Please note that the Message ID you entered must be under your user email. It is suggested to run the Get User List to find your desired email, then use the email to run Search Email command. Use the pair to run this command to delete your desired email.

Input

Input Parameter

Required/Optional

Description

Example

User Email

Required

The email address of the inbox to delete emails. User Email can be obtained using the Get User List command. Note: if using the OAuth Client ID authentication type to authenticate the integration connection, you can only delete emails of the google accounts who consent to your access.

test@example.com

Message IDs

Required

The IDs of the messages to delete. Message IDs can be obtained using the Search Emails command.

[ "***", "***" ]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON 
[
    {
        "messageID": "***",
        "actionResult": "Message is deleted successfully."
    },
    {
        "messageID": "***",
        "actionResult": "Message is deleted successfully."
    }
]
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

JSON 
{
  "MessageIDs": [
      "***",
      "***"
  ]
}
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 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 Gmail V2 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: User Email not found.

Error Sample Data

Delete Emails failed.

Status Code: 404.

Message: User Email not found.

Delete Users

Deletes the specified users. Note: If your connection uses OAuth Client ID authentication, the authenticated Google account must possess user management permissions.

Reader Note

Input parameter User Email or ID is required to run this command.

  • Run the Get User List command to obtain the User Email or ID. User ID can be found from the returned raw data at the path $.users[*].id. User Email can be found from the returned raw data at the path $.users[*].primaryEmail.

Input

Input Parameter

Required/Optional

Description

Example

User Email Or ID

Required

The email addresses or IDs of the users to delete. User emails and IDs can be obtained using the Get User List command.

test@example.com

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON 
[
    {
        "userKey": "test@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

JSON 
{
  "userKeys": "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.

Delete Users 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 Gmail V2 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:Not Authorized to access this resource/api.

Error Sample Data

Delete Users failed.

Status Code: 403.

Message: Not Authorized to access this resource/api.

Download Email Attachment

Obtains the specified email attachment(s). Note: if using the OAuth Client ID authentication type to authenticate the integration connection, you can only download email attachment(s) from the google accounts who consent to your access.

Reader Note

User Email, Message ID and Attachment File Names are required parameters to run this command.

  • Run the Get User List command to obtain User Email. User Emails can be found from the returned raw data at the path $.users[*].primaryEmail.

  • Run the Search Emails command to obtain Message ID. Message IDs can be found from the returned raw data at the path $.messages[*].id.

  • Run the Get Email command to obtain Attachment File Names. Attachment File Names can be found from the returned raw data at the path $[*].payload.filename.

  • Please note that the message ID you entered must be under your user email. The attachment file names must be under the message ID.

    • It is suggested to run the Get User List command to find your desired email, then use the email to run the Search Emails command. Use the pair to run the Get Email command for the attachment file name.

    • The email message is not guaranteed to have an attachment. File name can be empty.

Input

Input Parameter

Required/Optional

Description

Example

User Email

Required

The email address of the inbox to download attachments. User Email can be obtained using the Get User List command. Note: if using the OAuth Client ID authentication type to authenticate the integration connection, you can only download email attachment(s) from the google accounts who consent to your access.

test@example.com

Message ID

Required

The ID of the message containing the attachments. Message IDs can be obtained using the Search Emails command.

18***0

Attachment File Names

Required

The names of the attachment files. File Names can be obtained using the Get Email command. Note: If multiple attachment files with the same File Name exist, then all files with the same File Name will be downloaded.

[ "***CC Records.csv", "***.png" ]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON 
[
    {
        "fileName": "*** CC Records.csv",
        "fileType": "text/csv",
        "fileID": "25",
        "md5": "***",
        "sha1": "***",
        "sha256": "***"
    },
    {
        "fileName": "***.png",
        "fileType": "image/png",
        "fileID": "26",
        "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

JSON 
{
  "D3FileIDs": [
      "25",
      "26"
  ]
}
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.

Download Email 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 Gmail V2 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: The message doesn't contain any attachments.

Error Sample Data

Download Email Attachment failed.

Status Code: 403.

Message: The message doesn't contain any attachments.

Fetch Event

Returns emails as Events from the platform based on specified criteria. Note: If your connection uses OAuth Client ID authentication, you can only fetch emails from the google accounts who consent your access.

Reader Note

User Email is a required parameter to run this command.

  • Run the Get User List command to obtain User Email. User Emails can be found from the returned raw data at the path $.users[*].primaryEmail.

Input

Input Parameter

Required/Optional

Description

Example

User Email

Required

The email address from which to fetch emails. User Emails can be obtained using the Get User List command. Note: If you use OAuth Client ID authentication type, you can only fetch email from the google account who consent your access.

test@example.com

Start Time

Required

The start time for fetching emails in UTC time.

2021-05-25 00:00

End Time

Required

The end time for fetching emails in UTC time.

2021-05-26 00:00

Number of Event(s) Fetched

Optional

The maximum number of emails to return.

100

Search Condition

Optional

The query to filter results. For more information about the query syntax, see Search operators you can use with Gmail or REST Resource: users.settings.filters | Gmail | Google Developers.

subject:test from:test@example.com

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON 
[
    {
        "id": "***",
        "threadId": "***",
        "labelIds": [
            "IMPORTANT",
            "CATEGORY_PERSONAL",
            "INBOX"
        ],
        "snippet": "Hi, I'm reporting a suspicious email. Please find the attached. Thanks. Best regards, Flora",
        "payload": {
            "partId": "",
            "mimeType": "multipart/mixed",
            "filename": "",
            "headers": [
                {
                    "name": "Delivered-To",
                    "value": "test@example.com"
                },
                {
                    "name": "Received",
                    "value": "by 2002:***:***:***:**:***:****:****with SMTP id ***;        Sun, 27 Nov 2022 17:19:55 -0800 (PST)"
                },
                {
                    "name": "X-Received",
                    "value": "by 2002:***:***:***:**:***:****:****with SMTP id ***-***.***;        Sun, 27 Nov 2022 17:19:55 -0800 (PST)"
                },
                {
                    "name": "ARC-Seal",
                    "value": "i=1; a=rsa-sha256; t=***; cv=none;        d=google.com; s=arc-20160816;        b=******/***+***+bo         ***/**/****+****+*****=="
                }
            ],
            "body": {
                "size": 0
            },
            "parts": [
                {
                    "partId": "0",
                    "mimeType": "multipart/alternative",
                    "filename": "",
                    "headers": [
                        {
                            "name": "Content-Type",
                            "value": "multipart/alternative; boundary=\"***\""
                        }
                    ],
                    "body": {
                        "size": 0
                    },
                    "parts": [
                        {
                            "partId": "0.0",
                            "mimeType": "text/plain",
                            "filename": "",
                            "headers": [
                                {
                                    "name": "Content-Type",
                                    "value": "text/plain; charset=\"***-8\""
                                }
                            ],
                            "body": {
                                "size": 103,
                                "decodedData": "Hi,I'm reporting a suspicious email.Please find the attached. Thanks.  Best regards, *Flora*",
                                "data": "***=="
                            }
                        },
                        {
                            "partId": "0.1",
                            "mimeType": "text/html",
                            "filename": "",
                            "headers": [
                                {
                                    "name": "Content-Type",
                                    "value": "text/html; charset=\"UTF-8\""
                                },
                                {
                                    "name": "Content-Transfer-Encoding",
                                    "value": "quoted-printable"
                                }
                            ],
                            "body": {
                                "size": 433,
                                "data": "***-***-**-**-*-*-***",
                                "decodedData": "<div dir=\"ltr\"><div>Hi,</div><div><br></div><div>I&#39;m reporting a suspicious email.</div><div>Please find the attached. Thanks.</div><div><br></div>Best regards,<br clear=\"all\"><div><div dir=\"ltr\"><div dir=\"ltr\"><div><b>Flora</b></div><br class=\"gmail-Apple-interchange-newline\"></div></div></div><div><div dir=\"ltr\" class=\"gmail_signature\" data-smartmail=\"gmail_signature\"><div dir=\"ltr\"><div><br></div></div></div></div></div>"
                            }
                        }
                    ]
                },
                {
                    "partId": "1",
                    "mimeType": "message/rfc822",
                    "filename": "Survey.eml",
                    "headers": [
                        {
                            "name": "Content-Type",
                            "value": "message/rfc822; name=\"Survey.eml\""
                        },
                        {
                            "name": "Content-Disposition",
                            "value": "attachment; filename=\"Survey.eml\""
                        },
                        {
                            "name": "Content-ID",
                            "value": "<f_lb03rocz0>"
                        },
                        {
                            "name": "X-Attachment-Id",
                            "value": "f_lb03rocz0"
                        }
                    ],
                    "body": {
                        "attachmentId": "ANGjdJ-E230n_***",
                        "size": 6359
                    },
                    "parts": [
                        {
                            "partId": "1.0",
                            "mimeType": "multipart/mixed",
                            "filename": "",
                            "headers": [
                                {
                                    "name": "Delivered-To",
                                    "value": "xzang@d3security.com"
                                },
                                {
                                    "name": "Received",
                                    "value": "by 2002:a17:906:ce56:b0:7ba:44f7:f7ca with SMTP id se22csp3641265ejb;        Sun, 27 Nov 2022 16:58:39 -0800 (PST)"
                                },
                                {
                                    "name": "X-Received",
                                    "value": "by 2002:a63:5758:0:b0:477:fb27:ea7e with SMTP id h24-20020a635758000000b00477fb27ea7emr7310927pgm.551.1669597118846;        Sun, 27 Nov 2022 16:58:38 -0800 (PST)"
                                },
                                {
                                    "name": "ARC-Seal",
                                    "value": "i=1; a=rsa-sha256; t=1669597118; cv=none;        d=google.com; s=arc-20160816;        b=WFDE/weUeci66UQp6tc/g8AP+ZiZW41R6rrzxpzOr7sqxhsSqFn+67HL6SxcuCyUc+         q/zV1FVMgoIYInD7vNSY6LUgtvK1g/7v0/h05GDHycYQlT+TM/FJDOc56r6IqgBEIXwP         SOkH5qcmg2I5u7EbcdNMwisI5xODsf9oJoIAcUF9ga1ZoROziwaOv1/MMEl7RQM6mw6H         /so3r/8548DgRkBeZR6+JO1N7t03aC5yN/g0PnSxp/eC5sOa8uwPpVjJhKSMyug0E7nd         Da7GYhe2VZ3egzx+7PdpcgD5DGIH/+ZQPixNmEjQTE3gPVRRlKSYzOsIy+JvZtEopvu3         Gviw=="
                                },
                                {
                                    "name": "ARC-Message-Signature",
                                    "value": "i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816;        h=to:subject:message-id:date:from:mime-version:dkim-signature;        bh=w0y+5Y/phXf9UnBqXzBVk4i9kmbLRWJYnGUvR1QH7UM=;        b=SjZSuczOA4bw+hKx04KgU6diPFQqR4mmAXN0KVRTJq6iJP+/TEUHiFLFQ4o1k20fm5         U8qgHfd9yzBFKLMQl46AqoZPcoueoH14ytvV9xb9XXMiifNf1wYpZtVrs+VIPUQ+IwJK         vv0He6EB6WwU1BaAHm7sIZOeAYhZp4lOLMUAvlLd9lZGpeMOYRvlAElQNhQYeRZSdKKf         1JS04uRRdI5ycYGwS06TTVMui4kNJ5XHaiRy36hwCsW5/X8vbtSF98+4JebNXamyqmy3         8NzfoA55FFPDCwIOSWmBzzHu8TjF5htQshN5PyFyZbm3qFEiDhVKg12+CFKJasi8myQz         +27Q=="
                                },
                                {
                                    "name": "ARC-Authentication-Results",
                                    "value": "i=1; mx.google.com;       dkim=pass header.i=@gmail.com header.s=20210112 header.b=qrbjNVy+;       spf=pass (google.com: domain of xueminzang@gmail.com designates 209.85.220.41 as permitted sender) smtp.mailfrom=xueminzang@gmail.com;       dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com"
                                },
                                {
                                    "name": "Return-Path",
                                    "value": "<xueminzang@gmail.com>"
                                },
                                {
                                    "name": "Received",
                                    "value": "from mail-sor-f41.google.com (mail-sor-f41.google.com. [209.85.220.41])        by mx.google.com with SMTPS id d15-20020a056a00198f00b0056ba74154ebsor4828556pfl.96.2022.11.27.16.58.38        for <xzang@d3security.com>        (Google Transport Security);        Sun, 27 Nov 2022 16:58:38 -0800 (PST)"
                                },
                                {
                                    "name": "Received-SPF",
                                    "value": "pass (google.com: domain of xueminzang@gmail.com designates 209.85.220.41 as permitted sender) client-ip=209.85.220.41;"
                                },
                                {
                                    "name": "Authentication-Results",
                                    "value": "mx.google.com;       dkim=pass header.i=@gmail.com header.s=20210112 header.b=qrbjNVy+;       spf=pass (google.com: domain of xueminzang@gmail.com designates 209.85.220.41 as permitted sender) smtp.mailfrom=xueminzang@gmail.com;       dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com"
                                },
                                {
                                    "name": "DKIM-Signature",
                                    "value": "v=1; a=rsa-sha256; c=relaxed/relaxed;        d=gmail.com; s=20210112;        h=to:subject:message-id:date:from:mime-version:from:to:cc:subject         :date:message-id:reply-to;        bh=w0y+5Y/phXf9UnBqXzBVk4i9kmbLRWJYnGUvR1QH7UM=;        b=qrbjNVy+r23y8Oh+QBgI3xjy4/I4rnaOTNBMnk59xOQ7otuEZfwl/9s6yBky9Uex3v         VOGVjbBOjvsma5Hg8FiX61kqtzHzdZU/G+J6zb+nPaN51btj4rruOY6BZMli9crE74uX         9dv+vHXGctioZDo476LLxQP+ZRrplyvSsMks2h2qP/Yrwt1jCX2viXFmYxb4u7HytkT5         upyoWjUNlIz+Hjr4zciJfcCapIXbYRt2zcYS2+kJwQ7qt5JMLcNKPCW5fL8qQOlixk9a         D5mmbk4Dslkl6aDWc65erBxfWOEdAjbw6ybjk7FjJLEmwa0/ywXYNLPLZNDgRJaYB4vs         jKLA=="
                                },
                                {
                                    "name": "X-Google-DKIM-Signature",
                                    "value": "v=1; a=rsa-sha256; c=relaxed/relaxed;        d=1e100.net; s=20210112;        h=to:subject:message-id:date:from:mime-version:x-gm-message-state         :from:to:cc:subject:date:message-id:reply-to;        bh=w0y+5Y/phXf9UnBqXzBVk4i9kmbLRWJYnGUvR1QH7UM=;        b=5CDZZNInfkPgvWYZreRRPZdW724/QCaGdhtTyxajZ8YQaLO0e4SZVRGwz+y8CvT3Gw         3G222bf3Y3tK3yTcpPk/yrXt5RYl2xTVGBLNrsCBzagieJLHrr+iOYUa5AhGrLufTwQX         QK/9kFJZ0Pk44Q2xT73VjRLVmp5zUs3FvDX7UMUFwzqH5zN/2CllV71XE2pgXZdfLFcT         EBIFEt9P6+HeFpKAU5ZHVimvZzciUq8obi6TCqi6597w4HrzChRKysD+cRLRJVGf3jxc         qWV+o5qcIJwXGl3hiV5ofX3PDYimVpQkGQ94ldJdqbE/gVmkf46SFqeTer4OGrkMFoEa         GE5A=="
                                },
                                {
                                    "name": "X-Gm-Message-State",
                                    "value": "ANoB5pmUkWNJ+iFrIzYjLDo9SBIihhoq/WUXSyiFjtJkfq6URSRvchFh 0IUnGf7VeOEi9xBrIIdbA9YwuZARHe9VpMx+TWLcoZNQ"
                                },
                                {
                                    "name": "X-Google-Smtp-Source",
                                    "value": "AA0mqf6jV69yr6Z7WsMw+CANDvwkRBYtuJIP4rhAqJKrbmsK1dA5nSIlTJv19SyB4MSHgH79GKvN9ZGePzZbLKVVOX0="
                                },
                                {
                                    "name": "X-Received",
                                    "value": "by 2002:a05:6a00:410b:b0:56b:dc84:7783 with SMTP id bu11-20020a056a00410b00b0056bdc847783mr34297515pfb.35.1669597118053; Sun, 27 Nov 2022 16:58:38 -0800 (PST)"
                                },
                                {
                                    "name": "MIME-Version",
                                    "value": "1.0"
                                },
                                {
                                    "name": "From",
                                    "value": "Xuemin Zang <xueminzang@gmail.com>"
                                },
                                {
                                    "name": "Date",
                                    "value": "Sun, 27 Nov 2022 16:58:26 -0800"
                                },
                                {
                                    "name": "Message-ID",
                                    "value": "<CAGJYR=iEGS1fFygBDKXP-zEidg5X46-_pNPeY5WAcq5zT_6o_A@mail.gmail.com>"
                                },
                                {
                                    "name": "Subject",
                                    "value": "Survey"
                                },
                                {
                                    "name": "To",
                                    "value": "Flora Zang <xzang@d3security.com>"
                                },
                                {
                                    "name": "Content-Type",
                                    "value": "multipart/mixed; boundary=\"00000000000024401d05ee7d5f47\""
                                }
                            ],
                            "body": {
                                "size": 0
                            },
                            "parts": [
                                {
                                    "partId": "1.0.0",
                                    "mimeType": "multipart/alternative",
                                    "filename": "",
                                    "headers": [
                                        {
                                            "name": "Content-Type",
                                            "value": "multipart/alternative; boundary=\"00000000000024401a05ee7d5f45\""
                                        }
                                    ],
                                    "body": {
                                        "size": 0
                                    },
                                    "parts": [
                                        {
                                            "partId": "1.0.0.0",
                                            "mimeType": "text/plain",
                                            "filename": "",
                                            "headers": [
                                                {
                                                    "name": "Content-Type",
                                                    "value": "text/plain; charset=\"UTF-8\""
                                                }
                                            ],
                                            "body": {
                                                "size": 117,
                                                "data": "***",
                                                "decodedData": "Hi There, Please complete the survey, and you can get a chance to win $5000!!! http://xmr.pool.***.com/"
                                            }
                                        },
                                        {
                                            "partId": "1.0.0.1",
                                            "mimeType": "text/html",
                                            "filename": "",
                                            "headers": [
                                                {
                                                    "name": "Content-Type",
                                                    "value": "text/html; charset=\"***-8\""
                                                },
                                                {
                                                    "name": "Content-Transfer-Encoding",
                                                    "value": "quoted-printable"
                                                }
                                            ],
                                            "body": {
                                                "size": 706,
                                                "data": "**-*-***",
                                                "decodedData": "<div><div dir=\"ltr\"><div class=\"gmail_default\" style=\"font-family:simsun,serif;font-size:small\">Hi There,</div><div class=\"gmail_default\" style=\"font-family:simsun,serif;font-size:small\"><br></div><div class=\"gmail_default\" style=\"font-family:simsun,serif;font-size:small\">Please complete the survey, and you can get a chance to win $5000!!!</div><div class=\"gmail_default\" style=\"font-family:simsun,serif;font-size:small\"><br></div><div class=\"gmail_default\" style=\"font-family:simsun,serif;font-size:small\"><a href=\"http://xmr.pool.minergate.com/\" style=\"color:rgb(0,0,170);font-family:Verdana,Geneva,sans-serif;font-size:12px\" target=\"_blank\">http://xmr.pool.minergate.com/</a><br></div></div></div>"
                                            }
                                        }
                                    ]
                                },
                                {
                                    "partId": "1.***",
                                    "mimeType": "text/plain",
                                    "filename": "Phishing Attachment.txt",
                                    "headers": [
                                        {
                                            "name": "Content-Type",
                                            "value": "text/plain; charset=\"US-***\"; name=\"Phishing Attachment.txt\""
                                        },
                                        {
                                            "name": "Content-Disposition",
                                            "value": "attachment; filename=\"Phishing Attachment.txt\""
                                        },
                                        {
                                            "name": "Content-Transfer-Encoding",
                                            "value": "base64"
                                        },
                                        {
                                            "name": "Content-ID",
                                            "value": "<***>"
                                        },
                                        {
                                            "name": "X-Attachment-Id",
                                            "value": "***"
                                        }
                                    ],
                                    "body": {
                                        "attachmentId": "***",
                                        "size": 66
                                    }
                                }
                            ]
                        }
                    ]
                }
            ]
        },
        "AttachedEMLAttachementFiles": [
            {
                "D3fileName": "Survey.eml",
                "mimeType": "message/rfc822",
                "attachmentId": "***",
                "fileId": "355",
                "md5": "***",
                "sha1": "***",
                "sha256": "***",
                "From": "test user <test@example.com>",
                "To": "user test <user@example.com>",
                "Subject": "Survey",
                "Message-ID": "<***-***-****@mail.gmail.com>",
                "decodedData": "Hi There, Please complete the survey, and you can get a chance to win $5000!!! http://xmr.pool.minergate.com/"
            },
            {
                "D3fileName": "Survey.eml_Phishing Attachment.txt",
                "ParentEmail": "Survey.eml",
                "mimeType": "text/plain",
                "attachmentId": "***-***-***-***-***-curB",
                "fileId": "356",
                "md5": "***",
                "sha1": "***",
                "sha256": "***"
            }
        ],
        "sizeEstimate": 12103,
        "historyId": "***",
        "internalDate": "1669598387000"
    }
]
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

JSON 
{
  "MessageIDs": ["***"],
  "ThreadIDs": ["***"],
  "Snippets": ["This is test"],
  "FileIDs": ["256"]
}
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 D3 system fields which are standardized by the D3 data model. You can edit the provided mapping or customize new mappings to suit your needs. Please refer to Event and Incident Intake Field Mapping for more 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 Gmail V2 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 Event Source 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 Unique Event Key field would be id. Putting it together, the JSON Path expression to extract the Unique Event Key is $.id.

The pre-configured field mappings are detailed below:

Field Name

Source Field

Unique Event Key

.id

Event Type

*Email Alerts

Email subject

.payload.headers[?(@.name=='Subject')].value

Message body

.payload.HTMLBody

Sender

.payload.headers[?(@.name=='From')].value

Recipient

.payload.headers[?(@.name=='To')].value

CcRecipients

.payload.headers[?(@.name=='Cc')].value

BccRecipients

.payload.headers[?(@.name=='Bcc')].value

Description

.payload.snippet

Start Time

.internalDate

Message ID

.payload.headers[?(@.name=='Message-ID')].value

Attached EML File Name

.payload.parts[?(@.mimeType=='message/rfc822')].filename

Attached EML Sender

.payload.parts[?(@.mimeType=='message/rfc822')].headers[?(@.name=='From')].value

Attached EML Recipient

.payload.parts[?(@.mimeType=='message/rfc822')].parts[*].headers[?(@.name=='To')].value

Attached EML CcRecipients

.payload.parts[?(@.mimeType=='message/rfc822')].parts[*].headers[?(@.name=='Cc')].value

Attached EML BccRecipients

.payload.parts[?(@.mimeType=='message/rfc822')].parts[*].headers[?(@.name==’Bcc’)].value

Attached EML Subject

.payload.parts[?(@.mimeType=='message/rfc822')].parts[*].headers[?(@.name=='Subject')].value

Attached EML Message ID

.payload.parts[?(@.mimeType=='message/rfc822')].parts[*].headers[?(@.name=='Message-ID')].value

Attached EML Sent Date

.payload.parts[?(@.mimeType=='message/rfc822')].parts[*].headers[?(@.name=='Date')].value

Attached EML Body

.payload.parts[?(@.mimeType=='message/rfc822')].parts[*].parts[?(@.filename=='' && @.mimeType=='text/plain')].body.data

Attached EML Attachment File Names

.AttachedEMLAttachementFiles[*].D3fileName

Attached EML Attachment File Types

.AttachedEMLAttachementFiles[*].mimeType

Attached EML Attachment IDs

.AttachedEMLAttachementFiles[*].attachmentId

Attached EML Attachment D3 File IDs

.AttachedEMLAttachementFiles[*].fileId

Attached EML Attachment MD5

.AttachedEMLAttachementFiles[*].md5

Attached EML Attachment SHA1

.AttachedEMLAttachementFiles[*].sha1

Attached EML Attachment SHA256

.AttachedEMLAttachementFiles[*].sha256

Decoded Body Data

.DecodedBodyData

Attached EML Attachment Nested Email From

.AttachedEMLAttachementFiles[*].From

Attached EML Attachment Nested Email To

.AttachedEMLAttachementFiles[*].To

Attached EML Attachment Nested Email Subjects

.AttachedEMLAttachementFiles[*].Subject

Reader Note

*Email Alerts

In D3 SOAR, the events from Gmail V2 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 Source Field Type from Event and Incident Intake Field Mapping 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 Gmail V2 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: Delegation denied for your email address.

Error Sample Data

Fetch Event failed.

Status Code: 403.

Message: Delegation denied for your email address.

Get Auto Reply

Retrieves the auto-reply settings of the specified account. Note: If your connection uses OAuth Client ID authentication, you can only get vacation responder settings from the google account who consent your access.

Reader Note

User Email is a required parameter to run this command.

  • Run the Get User List command to obtain the User Email. User Emails can be found from the returned raw data at the path $.users[*].primaryEmail.

Input

Input Parameter

Required/Optional

Description

Example

User Email

Required

The email address to retrieve auto-reply settings for. User Emails can be obtained using the Get User List command. If your connection uses OAuth Client ID authentication, you can only get vacation responder settings from the google account who consent your access.

test@example.com

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON 
{
    "enableAutoReply": true,
    "responseSubject": " This is an auto reply message!",
    "responseBodyPlainText": "Sorry, I am not available now.",
    "restrictToContacts": false,
    "restrictToDomain": false,
    "startTime": "1652142600000",
    "endTime": "1653957000000"
}
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

JSON 
{
  "EnableAutoReply": true
}
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 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 Gmail V2 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: Invalid email input.

Error Sample Data

Get Auto Reply failed.

Status Code: 403.

Message: Invalid email input.

Get Email

Retrieves email for the specified email address and message ID. If your connection uses OAuth Client ID authentication, you can only get emails for the google accounts who consent to your access.

Reader Note

User Email and Message ID are required parameters to run this command.

  • Run the Get User List command to obtain the User Email. User Emails can be found from the returned raw data at the path $.users[*].primaryEmail.

  • Run the Search Emails command to obtain the Message IDs. Message IDs can be found from the returned raw data at the path $.messages[*].id.

  • Please note that the message ID you entered must be under your user email. It is suggested to run the Get User List command to find your desired email, then use the email to run the Search Emails command. Use the pair to run this command to get your desired email.

Input

Input Parameter

Required/Optional

Description

Example

User Email

Required

The email address to retrieve the email from. User Emails can be obtained using the Get User List command. If your connection uses OAuth Client ID authentication, you can only get emails for the google accounts who consent to your access.

test@example.com

Message IDs

Required

The message IDs for retrieving the email. Message IDs can be obtained using the Search Emails command.

[ "18***2" ]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON 
[
    {
        "id": "1***2",
        "threadId": "1***d",
        "labelIds": [
            "SENT"
        ],
        "snippet": "---------- Forwarded message --------- From: test user&lt;test@example.com&gt; Date: Tue, 17 May 2022 at 18:27 Subject: important info To: user test &lt;test@example.com&gt;",
        "payload": {
            "partId": "",
            "mimeType": "multipart/alternative",
            "filename": "",
            "headers": [
                {
                    "name": "MIME-Version",
                    "value": "1.0"
                },
                {
                    "name": "Date",
                    "value": "Tue, 17 May 2022 18:28:12 -0700"
                },
                {
                    "name": "References",
                    "value": "<***@mail.gmail.com>"
                },
                {
                    "name": "In-Reply-To",
                    "value": "<***@mail.gmail.com>"
                },
                {
                    "name": "Message-ID",
                    "value": "<***-***@mail.gmail.com>"
                },
                {
                    "name": "Subject",
                    "value": "Fwd: important info"
                },
                {
                    "name": "From",
                    "value": "test user <test@example.com>"
                },
                {
                    "name": "To",
                    "value": "test@example.com"
                },
                {
                    "name": "Content-Type",
                    "value": "multipart/alternative; boundary=\"***\""
                }
            ],
            "body": {
                "size": 0
            },
            "parts": [
                {
                    "partId": "0",
                    "mimeType": "text/plain",
                    "filename": "",
                    "headers": [
                        {
                            "name": "Content-Type",
                            "value": "text/plain; charset=\"***-8\""
                        }
                    ],
                    "body": {
                        "size": 186,
                        "data": "***"
                    }
                },
                {
                    "partId": "1",
                    "mimeType": "text/html",
                    "filename": "",
                    "headers": [
                        {
                            "name": "Content-Type",
                            "value": "text/html; charset=\"**-8\""
                        },
                        {
                            "name": "Content-Transfer-Encoding",
                            "value": "quoted-printable"
                        }
                    ],
                    "body": {
                        "size": 509,
                        "data": "**-**-**-***-*-**-**-*-**-**-DQo="
                    }
                }
            ]
        },
        "sizeEstimate": 1455,
        "historyId": "**",
        "internalDate": "1652837292000"
    }
]
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

JSON 
{
  "MessageIDs": ["***"],
  "ThreadIDs": ["***"],
  "Snippets": [test user <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 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 Gmail V2 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:Invalid id value.

Error Sample Data

Get Email failed.

Status Code: 403.

Message: Invalid id value.

Get User List

Retrieves a list of user details based on the specified criteria. If your connection uses OAuth Client ID authentication, the authenticated Google account must possess user management permissions.

Reader Note

Customer ID or Domain Name and Type are required parameters to run this command.

  • If you used the Create User command to create the user, then the Customer ID can be obtained after you've successfully created the user.

  • Your domain can be found on the Welcome page upon login, as shown in the example below.

Input

Input Parameter

Required/Optional

Description

Example

Customer ID or Domain Name

Required

The customer ID or domain name from which to get the user list. If the Type parameter is set to Domain, the input must be a domain. If the Type parameter is set to Customer, the input must be a Customer ID. If you don't know the Customer ID, you can input "my_customer", all users will be returned.

example.com

Type

Required

The type of the name. Choose either Customer or Domain.

Domain

Limit

Optional

The maximum number of results to return. If not specified, all users will be returned.

10

Order By

Optional

The property to sort results by.

Email

Filter

Optional

The query statement to filter results. For more information about the query syntax, see Search for users | Admin console | Google Developers

name:'Test User' isadmin=false

Sort Order

Optional

The option to sort results in ascending or descneding order, ignoring case sensitivity.

Ascending

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON 
{
    "kind": "admin#directory#users",
    "etag": "\"3***/***\"",
    "users": [
        {
            "kind": "admin#directory#user",
            "id": "***",
            "etag": "\"***/***\"",
            "primaryEmail": "test@example.com",
            "name": {
                "givenName": "Test",
                "familyName": "User",
                "fullName": "Test User"
            },
            "isAdmin": false,
            "isDelegatedAdmin": false,
            "lastLoginTime": "1970-01-01T00:00:00.000Z",
            "creationTime": "2022-05-17T19:44:35.000Z",
            "agreedToTerms": false,
            "suspended": false,
            "archived": false,
            "changePasswordAtNextLogin": true,
            "ipWhitelisted": false,
            "emails": [
                {
                    "address": "test@example.com",
                    "primary": true
                },
                {
                    "address": "test@example.com.test.com"
                }
            ],
            "phones": [
                {
                    "value": "+1 604 123 4567",
                    "type": "work"
                }
            ],
            "languages": [
                {
                    "languageCode": "en-GB",
                    "preference": "preferred"
                }
            ],
            "nonEditableAliases": [
                "test@example.com.test.com"
            ],
            "customerId": "***",
            "orgUnitPath": "/",
            "isMailboxSetup": true,
            "isEnrolledIn2Sv": false,
            "isEnforcedIn2Sv": false,
            "includeInGlobalAddressList": 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

JSON 
{
  "UserIDs": "10***5"
}
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 User List 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 Gmail V2 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: Bad request on customer.

Error Sample Data

Get User List failed.

Status Code: 403.

Message: Bad request on customer.

Label Emails

Adds or removes labels from the specified emails. Note: If your connection uses OAuth Client ID authentication, you can only label emails of the google accounts who consent to your access.

Reader Note

User Email and Message IDs are required parameters to run this command.

  • Run the Get User List command to obtain the User Email. User Emails can be found from the returned raw data at the path $.users[*].primaryEmail.

  • Run the Search Emails command to obtain the Message IDs. Message IDs can be found from the returned raw data at the path $.messages[*].id.

  • Please note that the message ID you entered must be under your user email. It is suggested to run the Get User List command to find your desired email, then use the email to run the Search Emails command. Use the pair to run this command to label your desired email.

Add Label and Remove Label are optional parameters to run this command.

  • Run the List Labels command to get the available labels to add. Labels can be found from the returned raw data at the path $.labels[*].id.

  • Run the Get Emails or Fetch Event command to check the existing labels in the message ID you've entered. Attached labels can be found in the returned raw data at the path $.[*]labelIds for both commands. Please note that you've already specified the message ID in the Get Email command, so the labels are ready to use; for the Fetch Event command, please make sure the JSON object is for your desired message ID before using those labels.

  • The label must exist, no labels will be added/removed for non-existing labels. If you remove a label that has not been labeled before in the email, the command will run successfully with no result.

Input

Input Parameter

Required/Optional

Description

Example

User Email

Required

The email address to apply the label updates to. Existing User Emails can be obtained using the Get User List command. Please note, if you use OAuth Client ID authentication type, you can only label emails of the google accounts who consent to your access.

test@example.com

Message IDs

Required

The IDs of the messages to apply the label updates to Message IDs can be obtained using the Search Emails command.

[ "1***2" ]

Add Labels

Optional

The labels to add onto the email(s). You can get the available Label IDs for the specified email using the List Labels command. Note: At least one parameter from Add or Remove Labels must be specified. You can remove and add labels simultaneously.

[ "CATEGORY_SOCIAL", "IMPORTANT" ]

Remove Labels

Optional

The labels to remove from the email(s). You can get the current Label IDs for the specified email using the Get Emails or Fetch Event command. Note: At least one parameter from Add or Remove Labels must be specified. You can remove and add labels simultaneously.

["STARRED"]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON 
[
    {
        "id": "1***2",
        "threadId": "1***d",
        "labelIds": [
            "IMPORTANT",
            "CATEGORY_SOCIAL",
            "SENT"
        ]
    }
]
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

JSON 
{
  "MessageIDs": ["1***2"],
  "ThreadIDs": ["1***d"]
}
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.

Label 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 Gmail V2 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 id value.

Error Sample Data

Label Emails failed.

Status Code: 403.

Message: Invalid id value.

List Labels

Lists all labels in the specified user's mailbox. Note: If your connection uses OAuth Client ID authentication, you can only list labels of the google accounts who consent to your access.

Reader Note

User Email is a required parameter to run this command.

  • Run the Get User List command to obtain the User Email. User Emails can be found from the returned raw data at the path $.users[*].primaryEmail.

Input

Input Parameter

Required/Optional

Description

Example

User Email

Required

The email address from which to retrieve existing labels. Note: If your connection uses OAuth Client ID authentication, you can only list labels of the google accounts who consent to your access.

test@example.com

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON 
{
    "labels": [
        {
            "id": "CHAT",
            "name": "CHAT",
            "messageListVisibility": "hide",
            "labelListVisibility": "labelHide",
            "type": "system"
        },
        {
            "id": "SENT",
            "name": "SENT",
            "type": "system"
        },
        {
            "id": "INBOX",
            "name": "INBOX",
            "type": "system"
        },
        {
            "id": "IMPORTANT",
            "name": "IMPORTANT",
            "messageListVisibility": "hide",
            "labelListVisibility": "labelHide",
            "type": "system"
        },
        {
            "id": "TRASH",
            "name": "TRASH",
            "messageListVisibility": "hide",
            "labelListVisibility": "labelHide",
            "type": "system"
        },
        {
            "id": "DRAFT",
            "name": "DRAFT",
            "type": "system"
        },
        {
            "id": "SPAM",
            "name": "SPAM",
            "messageListVisibility": "hide",
            "labelListVisibility": "labelHide",
            "type": "system"
        },
        {
            "id": "CATEGORY_FORUMS",
            "name": "CATEGORY_FORUMS",
            "messageListVisibility": "hide",
            "labelListVisibility": "labelHide",
            "type": "system"
        },
        {
            "id": "CATEGORY_UPDATES",
            "name": "CATEGORY_UPDATES",
            "messageListVisibility": "hide",
            "labelListVisibility": "labelHide",
            "type": "system"
        },
        {
            "id": "CATEGORY_PERSONAL",
            "name": "CATEGORY_PERSONAL",
            "messageListVisibility": "hide",
            "labelListVisibility": "labelHide",
            "type": "system"
        },
        {
            "id": "CATEGORY_PROMOTIONS",
            "name": "CATEGORY_PROMOTIONS",
            "messageListVisibility": "hide",
            "labelListVisibility": "labelHide",
            "type": "system"
        },
        {
            "id": "CATEGORY_SOCIAL",
            "name": "CATEGORY_SOCIAL",
            "messageListVisibility": "hide",
            "labelListVisibility": "labelHide",
            "type": "system"
        },
        {
            "id": "STARRED",
            "name": "STARRED",
            "type": "system"
        },
        {
            "id": "UNREAD",
            "name": "UNREAD",
            "type": "system"
        },
        {
            "id": "Label_1",
            "name": "BLUE_TAG",
            "messageListVisibility": "show",
            "labelListVisibility": "labelShow",
            "type": "user"
        },
        {
            "id": "Label_2",
            "name": "RED_TAG",
            "messageListVisibility": "show",
            "labelListVisibility": "labelShow",
            "type": "user"
        }
    ]
}
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

JSON 
{
  "LabelIDs": "IMPORTANT",
  "LabelNames": "IMPORTANT"
}
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 Labels 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 Gmail V2 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: Invalid email value.

Error Sample Data

List Labels failed.

Status Code: 403.

Message: Invalid email input.

Report Spam

Marks the specified message as spam.

Reader Note

  • User Email and Message IDs are required parameters to run this command.

    • Run the Get User List command to obtain the User Email. User Emails can be found from the returned raw data at the path $.users[*].primaryEmail.

    • Run the Search Emails command to obtain the Message IDs. Message IDs can be found from the returned raw data at the path $.messages[*].id.

    • Please note that the message ID you entered must be under your user email. It is suggested to run the Get User List command to find your desired email, then use the email to run the Search Emails command. Use the pair to run this command to report your desired email as spam.

  • If an email is located in the inbox or any other folders (labels), running this command will move the email to the SPAM folder. However, it will not alter other labels that remain unaffected, such as SENT, UNREAD, etc.

Input

Input Parameter

Required/Optional

Description

Example

User Email

Required

The user's email address. Existing User Emails can be obtained using the Get User List command. Note: If your connection uses OAuth Client ID authentication, you can only report Spam email from the google accounts who consent to your access.

test@example.com

Message IDs

Required

The IDs of the messages to be marked as spam. Message IDs can be obtained using the Search Emails command.

[ "17***7" ]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON 
{
    "id": "17***7",
    "threadId": "17***c",
    "labelIds": [
        "CATEGORY_PERSONAL",
        "SPAM"
    ]
}
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

JSON 
{
  "MessageIDs": "17***7",
  "ThreadIDs": "17***c",
  "LabelIDs": [
      "CATEGORY_PERSONAL",
      "SPAM"]
}
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.

Report Spam 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 Gmail V2 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 Message IDs value.

Error Sample Data

Report Spam failed.

Status Code: 403.

Message: Invalid Message IDs value.

Search Emails

Lists the emails in the user's mailbox based on specified criteria. Note: If your connection uses OAuth Client ID authentication, you can only search emails in the google account who consents to your access.

Reader Note

User Email is a required parameter to run this command.

  • Run the Get User List command to obtain the User Email. User Emails can be found from the returned raw data at the path $.users[*].primaryEmail.

The parameter Label IDs is optional to run this command.

  • Run the List Labels command to obtain the Label IDs. Label IDs can be found from the returned raw data at the path $.labels[*].id.

  • Please note that if this parameter is defined, then only the messages that match all the input labels will be returned.

Input

Input Parameter

Required/Optional

Description

Example

User Email

Required

The email address associated with the inbox being searched. Existing User Emails can be obtained using the Get User List command. Note: If your connection uses OAuth Client ID authentication, you can only search emails in the google accounts who consent to your access.

test@example.com

Filter

Optional

The query statement to filter emails. Supports the same query format as the Gmail search box. For example, "from:someuser@example.com rfc822msgid:<somemsgid@example.com> is:unread". For more information about the query syntax, see Search operators you can use with Gmail

subject:good from:test@example.com

Limit

Optional

The maximum number of emails to return. If this parameter is not defined, the default value is 100. The maximum allowed value is 500.

100

Label IDs

Optional

The Label IDs to search for. Only messages with labels that match all of the specified Label IDs will be returned. You can obtain the available Label IDs with the List Labels command.

[ "IMPORTANT", "CATEGORY_SOCIAL" ]

Include Spam Trash

Optional

The option to include emails from SPAM and TRASH in the results. If this parameter is not defined, the results will NOT include emails from SPAM and TRASH.

True

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON 
{
    "messages": [
        {
            "id": "18***c",
            "threadId": "18***c"
        }
    ],
    "resultSizeEstimate": 1
}
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

JSON 
{
  "MessageIDs": ["1***c"],
  "ThreadIDs": ["1***c"]
}
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.

Search 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 Gmail V2 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: Invalid label value.

Error Sample Data

Search Emails failed.

Status Code: 403.

Message: Invalid label value.

Send Email

Sends an email from the specified sender's email address. Note: If your connection uses OAuth Client ID authentication, you can only send email from the google accounts who consent to your access.

Reader Note

Input parameter User Email is required to run this command.

  • Run the Get User List command to obtain the User Email. User Emails can be found from the returned raw data at the path $.users[*].primaryEmail.

File ID and File Source

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

  1. In D3 SOAR, navigate to Configuration on the top bar menu.

  2. Click Utility Commands on the left sidebar menu.

  3. Use the search box to find and select the Create a File from input Text Array command.

  4. Select the Test tab, then input the required information for the parameters. Click Test Command.
    A D3 File ID will appear in the output data after the file has been successfully created.
    (Note: The D3 File Source of the created file will be Playbook File)

Input

Input Parameter

Required/Optional

Description

Example

Sender Email

Required

The sender's email address.

test@example.com

Subject

Required

The email's subject.

Test Email

Content

Optional

The content of the email. The content format can be plain text or HTML.

Hi<br/>Html Email

To Recipients

Optional

The To recipients of the email.

[ 'test@example.com' ]

CC Recipients

Optional

The CC recipients of the email.

[ 'test@example.com' ]

BCC Recipients

Optional

The BCC recipients of the email.

[ 'test@example.com' ]

File IDs

Optional

The file path of the email attachment files.

[ "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

IR Attachment

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON 
{
    "id": "17***1",
    "threadId": "17***1",
    "labelIds": [
        "SENT"
    ]
}
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

JSON 
{
  "MessageID": "17***1",
  "ThreadID": "17**1"
}
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 Email 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 Gmail V2 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: The Recipients contain invalid email address.

Error Sample Data

Send Email failed.

Status Code: 403.

Message: The Recipients contain invalid email address.

Set Auto Reply

Sets the auto-reply settings for an account. The auto-reply content format can be plain text or HTML. Note: If your connection uses OAuth Client ID authentication, you can only set Auto Reply from the google accounts who consent to your access.

Reader Note

User Email is a required parameter to run this command.

  • Run the Get User List command to obtain User Email. User Emails can be found from the returned raw data at the path $.users[*].primaryEmail.

Input

Input Parameter

Required/Optional

Description

Example

User Email

Required

The email address to update auto-reply settings for. Existing User Emails can be obtained using the Get User List command. Note: If your connection uses OAuth Client ID authentication, you can only set Auto Reply from the google accounts who consent to your access.

test@example.com

Enable Auto Reply

Optional

The option for Gmail to automatically reply to messages. If this parameter is not defined, the default value is False.

True

Response Subject

Optional

The subject of the auto-reply.

This is an auto reply message!

Response Body Plain Text

Optional

The content of the auto-reply email in either plain text or HTML.

<P>Happy Vacation</P>

Restrict To Contacts

Optional

The option to send auto-replies to recipients who are not in the user's list of contacts. If this parameter is not defined, the default value is False.

False

Restrict To Domain

Optional

The option to send auto-replies to recipients who are outside of the user's domain. This feature is only available for G Suite users. If this parameter is not defined, the default value is False.

False

Start Time

Optional

An optional start time for sending auto-replies. When this parameter is defined, Gmail will automatically reply only to messages that it receives after the Start Time. If both Start Time and End Time are defined, Start Time must precede End Time.

2022-05-20 00:00

End Time

Optional

An optional end time for sending auto-replies (epoch ms). When this parameter is defined, Gmail will automatically reply only to messages that it receives before the End Time. If both Start Time and End Time are defined, Start Time must precede End Time.

2022-05-30 00:00

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON 
{
    "enableAutoReply": true,
    "responseSubject": " This is an auto reply message!",
    "responseBodyPlainText": "Sorry, I am not available now.",
    "restrictToContacts": false,
    "restrictToDomain": false,
    "startTime": "1652142600000",
    "endTime": "1653957000000"
}
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

JSON 
{
  "EnableAutoReply": true
}
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.

Set 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 Gmail V2 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: Invalid email value.

Error Sample Data

Set Auto Reply failed.

Status Code: 403.

Message: Invalid email value.

Set User Password

Sets the password of the specified account. Note: If your connection uses OAuth Client ID authentication, the authenticated Google account must possess user management permissions.

Reader Note

User Key is a required parameter to run this command.

  • Run the Get User List command to obtain the User Email or User ID. User Emails can be found from the returned raw data at the path $.users[*].primaryEmail. User IDs can be found from the returned raw data at the path $.users[*].id.

Input

Input Parameter

Required/Optional

Description

Example

User Key

Required

The email address or ID of the user account to set the password for. Existing User Email or User IDs can be obtained using the Get User List command.

test@example.com

Password

Required

The password to apply to the user account. A password can contain any combination of ASCII characters. A minimum of 8 characters is required. The maximum length is 100 characters. The password value is never returned in the command's response body.

PASSword!@#$

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON 
{
    "kind": "admin#directory#user",
    "id": "***",
    "etag": "\"**/***\"",
    "primaryEmail": "test@example.com",
    "name": {
        "givenName": "Test",
        "familyName": "Example",
        "fullName": "Test Example"
    },
    "isAdmin": false,
    "isDelegatedAdmin": false,
    "lastLoginTime": "2022-05-18T19:59:33.000Z",
    "creationTime": "2022-05-17T19:44:35.000Z",
    "agreedToTerms": true,
    "suspended": false,
    "archived": false,
    "changePasswordAtNextLogin": false,
    "ipWhitelisted": false,
    "emails": [
        {
            "address": "test@example.com",
            "primary": true
        },
        {
            "address": "test@example.com.test-.com"
        }
    ],
    "phones": [
        {
            "value": "+1 604 123 4567",
            "type": "work"
        }
    ],
    "nonEditableAliases": [
        "test@example.com.test.com"
    ],
    "customerId": "***",
    "orgUnitPath": "/",
    "isMailboxSetup": true,
    "includeInGlobalAddressList": true,
    "recoveryEmail": ""
}
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

JSON 
{
  "UserID": "***"
}
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.

Set User Password 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 Gmail V2 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: Cannot find User Key.

Error Sample Data

Set User Password failed.

Status Code: 404.

Message: Cannot find User Key.

Trash Emails

Moves the specified emails to the trash. Note: If your connection uses OAuth Client ID authentication, you can only trash emails of the google accounts who consent to your access.

Reader Note

  • User Email and Message ID are required parameters to run this command.

    • Run the Get User List command to obtain the User Email. User Emails can be found from the returned raw data at the path $.users[*].primaryEmail.

    • Run the Search Emails command to obtain the Message IDs. Message IDs can be found from the returned raw data at the path $.messages[*].id.

    • Please note that the message ID you entered must be under your user email. It is suggested to run the Get User List to find your desired email, then use the email to run the Search Emails command. Use the pair to run this command to trash your desired email.

  • Error messages are not returned if the specified email is already in the trash when running this command.

  • If an email is located in the inbox or any other folders (labels), running this command will move the email to the TRASH folder. However, it will not alter other labels that remain unaffected, such as SENT, UNREAD, etc.

Input

Input Parameter

Required/Optional

Description

Example

User Email

Required

The email address from which to move emails to the trash bin. Existing User Emails can be obtained using the Get User List command. Note: If your connection uses OAuth Client ID authentication, you can only trash emails of the google accounts who consent to your access.

test@example.com

Message IDs

Required

The message ID(s) to move to the trash bin. Existing Message IDs can be obtained using the Search Emails command. Note: An error message is not returned if the specified email was not in the trash when running this command.

[ "1***4", "1***5" ]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON 
[
    {
        "id": "1***4",
        "threadId": "1***4",
        "labelIds": [
            "IMPORTANT",
            "TRASH",
            "CATEGORY_PERSONAL"
        ]
    }
]
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

JSON 
{
  "MessageIDs": [
      "1***4",
      "1***5"]
}
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.

Trash 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 Gmail V2 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 Message ID test@example.comvalue.

Error Sample Data

Trash Emails failed.

Status Code: 400.

Message: Invalid Message ID test@example.comvalue.

Untrash Emails

Removes the specified emails from the trash. Note: If your connection uses OAuth Client ID authentication, you can only untrash emails of the google accounts who consent to your access.

Reader Note

  • User Email and Message ID are required parameters to run this command.

    • Run the Get User List command to obtain the User Email. User Emails can be found from the returned raw data at the path $.users[*].primaryEmail.

    • Run the Search Emails command to obtain the Message IDs. Message IDs can be found from the returned raw data at the path $.messages[*].id.

    • Please note that the message id you entered must be under your user email. It is suggested to run the Get User List command to find your desired email, then use the email to run the Search Emails command. Use the pair to run this command to untrash your desired email.

  • Note: An error message is not returned if the specified email was not in the trash when running this command. If the trash bin has been emptied, the emails which were trashed cannot be untrashed.

  • If you take an email out of the trash folder (label) by using this command, the folder label will no longer exist after this command is run successfully.

Input

Input Parameter

Required/Optional

Description

Example

User Email

Required

The email address to restore emails to from the trash bin. Existing User Emails can be obtained using the Get User List command. Note: If your connection uses OAuth Client ID authentication, you can only untrash emails of the google accounts who consent to your access.

test@example.com

Message IDs

Required

The message ID(s) to remove from trash. Existing Message IDs can be obtained using the Search Emails command. If the email is not in the trash, it won’t return an error message. If the trash bin has been emptied, the emails which were trashed cannot be untrashed.

[ "1***4", "1***1" ]

Output

Raw Data

The primary response data from the API request.

SAMPLE DATA

JSON 
[
    {
        "id": "18***1",
        "threadId": "18***81",
        "labelIds": [
            "UNREAD",
            "IMPORTANT",
            "CATEGORY_PERSONAL",
            "INBOX"
        ],
        "snippet": "test test test test",
        "sizeEstimate": 137426,
        "historyId": "***",
        "internalDate": "1655842024000"
    }
]
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

JSON 
{
  "MessageIDs": [
      "18***4",
      "18***1"]
}
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.

Untrash 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 Gmail V2 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 Message ID value.

Error Sample Data

Untrash Emails failed.

Status Code: 400.

Message:: Invalid Message ID value.

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 Gmail V2 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: Invalid Client Secret provided.

Error Sample Data

Test Connection failed. Failed to check the connector.

Status Code: 404.

Message: Invalid Client Secret provided.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close