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:
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
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.
Click the Hamburger Menu in the top left corner to reveal the sidebar menu. Navigate to APIs and services. In its submenu, select Credentials.
Click + CREATE CREDENTIALS, and select Service account.
Input the Service account name and description, and click CREATE AND CONTINUE.
(Optional) Assign a role to the service account (e.g. owner), then click CONTINUE.
You can opt to grant users access to this service account. Click DONE to confirm your configurations.
You will find the service account you have just created on the credentials page. Click and open the service account.
In the KEYS tab, click ADD KEY, then select Create new key.
Choose JSON as the key type, then click CREATE.
The Service Account JSON file (Private key) will automatically be downloaded to your computer.
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.
Search for Gmail.
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.
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.
Click Add new to add a new API client.
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:
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
Finally, click AUTHORISE.
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.
Log in to the Google Cloud console with your admin account.
Navigate to APIs and services > Credentials > Create credentials > OAuth client ID.
Select Web Application for Authentication type.
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.
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.
Access the Google Admin, navigate to Directory > Users, and select the account you are configuring for OAuth credentials.
Scroll to the Roles section and assign the User Management admin role to this user.
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
Log in to D3 SOAR.
Find the Gmail V2 integration.
Navigate to Configuration on the top header menu.
Click on the Integration icon on the left sidebar.
Type Gmail V2 in the search box to find the integration, then click it to select it.
Click + New Connection, on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to Gmail V2.
Connection Name: The desired name for the connection.
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.
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.
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.
Description (Optional): Add your desired description for the connection.
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.
Configure User Permissions: Defines which users have access to the connection.
Active: Check the tick box to ensure the connection is available for use.
[IMAGE]System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
Authentication Type: Service Account1. 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 ID1. 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.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.
Connection Health Check: Updates the connection status you have created. A connection health check is done by scheduling the Test Connection command of this integration. This can only be done when the connection is active.
To set up a connection health check, check the Connection Health Check tickbox. You can customize the interval (minutes) for scheduling the health check. An email notification can be set up after a specified number of failed connection attempts.
Test the connection.
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.
Click OK to close the alert window.
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:
Navigate to Configuration > Application Settings. Select Date/Time Format.
Choose your desired date and time format.
After that, you will be able to view your preferred time format when configuring the DateTime input parameters for commands.
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
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
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
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
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
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
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
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. | |
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
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
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
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
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
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:
In D3 SOAR, navigate to Configuration on the top bar menu.
Click Utility Commands on the left sidebar menu.
Use the search box to find and select the Create a File from input Text Array command.
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
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
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
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
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
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
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. |