Cisco Email Security

LAST UPDATED: SEPTEMBER 18, 2025

Overview

Cisco Email Security is an email security gateway. It detects and blocks a wide variety of email-borne threats, such as malware, spam and phishing.

D3 SOAR is providing REST operations to function with Cisco Email Security.

Cisco Email Security is available for use in:

D3 SOAR	V14.0.20.0+
Category	Email Security
Deployment Options	Option I, Option III

Connection

To connect to Cisco Email Security from D3 SOAR, follow this part to collect the required information below:

Parameter	Description	Example
Server URL	The server URL of the Cisco Email Security environment.	https://1.1.1.1/
User Name	The username used for authentication.	Admin
Password	The password used for authentication.	Password
API Version	The version of the API used for the connection.	v2.0

Permission Requirements

Each endpoint in the Cisco Email Security API requires a certain permission scope. Configure the privileges based on the desired needs.

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

READER NOTE

Cisco Email Security’s default user profiles (sorted from the least permissions to the most) are as follows:

Administrator: Administrator user accounts have full access to all configuration settings of the system.
Operator: Operator user accounts are restricted from creating or editing new user accounts, issuing the resetconfig command, checking for or installing available upgrades, running the System Setup Wizard, and certain quarantine functions (including creating and deleting quarantines). Otherwise, they have the same privileges as Administrators.
Guest user: Guest user accounts may only view status information.
Read-Only Operator: Read-Only Operator user accounts can view configuration but cannot commit changes.
Technician: Technicians can only manage upgrades and feature keys.
Help Desk user: Help Desk user accounts can only access message tracking features. Help Desk User accounts can be invited to the IronPort Spam Quarantine or system quarantines.
Custom user: Custom user role accounts can only access email security features assigned to the role. These features can be any combination of DLP policies, email policies, reports, quarantines, local message tracking, encryption profiles, and the Trace debugging tool.

Configuring Cisco Email Security to Work with D3 SOAR

Log in to Cisco Email Security.

Creating a Role

Navigate to System Administration > User Roles to create roles.
Click Add User Role.
Name the role and configure the required Access Privileges. Click Submit to save the changes.

Creating a User

Navigate to System Administration > Users. Click Add User.
Enter the following information.
1. Name the user.
2. Define the user role. Select from the Predefined Roles or choose from Custom Roles, such as the role created in Creating a Role.
3. Confirm the passphrase (the password of the authenticated account).
4. Enter a passphrase for the user. Click Generate to create one or choose a passphrase.
Note: If creating a custom password, the passphrase must have:
- At least 8 characters
- At least one upper (A-Z) and one lower (a-z) case letter
- At least one special character
- No three or more repetitive or sequential characters (for example: AAA, DEF, FED).

5. Click Submit to create the user.

Configuring D3 SOAR to Work with Cisco Email Security

Log in to D3 SOAR.
Find the Cisco Email Security integration.
1. Navigate to Configuration on the top header menu.
2. Click on the Integration icon on the left sidebar.
3. Type Cisco Email Security in the search box to find the integration, then click it to select it.
4. Click + Connection, on the right side of the Connections section. A new connection window will appear.
Configure the following fields to create a connection to Cisco Email Security.
1. Connection Name: The desired name for the connection.
2. Site: The site on which to use the integration connection. Use the drop-down menu to select the site. The Share to Internal Sites option enables all internal sites to use the connection. Selecting a specific site will only enable that site to use the connection.
3. Recipient site for events from connections Shared to Internal Sites: This field is displayed when Share to Internal Sites is selected for the Site field, allowing selection of the internal site for deploying the integration connection.
4. Agent Name (Optional): 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): The description for the connection.
6. Tenant (Optional): When configuring the connection from a master tenant site, users can choose the specific tenant sites with which to share the connection. Once this setting is enabled, users can filter and select the desired tenant sites from the dropdowns to share the connection.
7. Configure User Permissions: Defines which users have access to the connection.
8. Active: The checkbox that enables the connection to be used when selected.
9. System: This section contains the parameters defined specifically for the integration. These parameters must be configured to create the integration connection.
  1. Input the Server URL.
  2. Input the User Name from the Cisco Email Security platform. Refer to Configuring Cisco Email Security to Work with D3 SOAR.
  3. Input the Password from the Cisco Email Security platform. Refer to Configuring Cisco Email Security to Work with D3 SOAR.
  4. Input the API Version. The default value is v2.0.
10. Enable Password Vault: An optional feature that allows users to take the stored credentials from their own password vault. Refer to the password vault connection guide if needed.
11. Connection Health Check: Periodically checks the connection status by scheduling the Test Connection command at the specified interval (in minutes). Available only for active connections, this feature also allows configuring email notifications for failed attempts.
Test the connection.
1. Click on the Test Connection button to verify credentials and connectivity. A success alert displays Passed with a green checkmark. If the connection fails, review the parameters and retry.
2. Click OK to close the alert window.
3. Click + Add to create and add the configured connection.

Commands

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

READER NOTE

Certain permissions are required for each command. Refer to the Permission Requirements and Configuring Cisco Email Security to Work with D3 SOAR for details.

Note for Time-related parameters

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

Navigate to Configuration > Application Settings. Select Date/Time Format.
Choose the desired date and time format, then click on the Save button.

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

Add Entries

Adds Safelist or Blocklist Entries in the spam quarantine.

Input

Input Parameter	Required/Optional	Description	Example
List Type	Required	The list type of the entry. Valid values are: Blocklist Safelist	Blocklist
Action	Required	The action of the entry. Valid values are: Add Edit Append	Append
View By	Required	The reviewer of the entry. Valid values are: Sender Recipient	Sender
Recipient Addresses	Required	The recipient addresses of the entry. This parameter is required when View By is set to Recipient.	JSON `[ "test1@example.com", "test2@example.com" ]`
Recipient List	Required	The recipient list of the entry. This parameter is required when View By is set to Sender.	JSON `[ "test1@example.com", "test2@example.com" ]`
Sender Addresses	Required	The sender addresses of the entry. This parameter is required when View By is set to Sender.	JSON `[ "example.com", "testsender.com" ]`
Sender List	Required	The sender list of the entry. This parameter is required when View By is set to Recipient.	JSON `[ "example.com", "testsender.com" ]`

Output

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

Error Handling

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

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

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Add Entries 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 Cisco Email Security portal. Refer to the HTTP Status Code Registry for details.	Status Code: 500.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Server got itself in trouble: The application raised an exception.

Error Sample Data

Add Entries failed.

Status Code: 500.

Message: Server got itself in trouble: The application raised an exception.

Block Domain

Adds, edits or appends blocklist entries viewed by sender or recipient.

Input

Input Parameter	Required/Optional	Description	Example
Action	Required	The action to perform on the blocklist in Cisco ESA. Valid options are: Add Edit Append	Append
View By	Required	The criteria used to apply blocklist entries. Valid options are: Sender Recipient	Sender
Sender Addresses	Optional	The sender domains on which to perform the action. This parameter is required when View By is set to Sender.	JSON `[ "example.com", "testsender.com" ]`
Recipients List	Optional	The recipient email addresses on which to perform the action. This parameter is required when View By is set to Sender.	JSON `[ "test1@example.com", "test2@example.com" ]`
Sender List	Optional	The sender domains on which to perform the action. This parameter is required when View By is set to Recipient.	JSON `[ "example.com", "testsender.com" ]`
Recipients Addresses	Optional	The recipient email addresses on which to perform the action. This parameter is required when View By is set to Recipient.	JSON `[ "test1@example.com", "test2@example.com" ]`

Output

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

Error Handling

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

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

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Block Domain 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 Cisco Email Security portal. Refer to the HTTP Status Code Registry for details.	Status Code: 400.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Please use the test command and check Raw Data for the details.

Error Sample Data

Block Domain failed.

Status Code: 400.

Message: Please use the test command and check Raw Data for the details.

Block Email Addresses

Adds or appends sender email addresses to blocklist entries that are applied and viewed by recipient.

Input

Input Parameter	Required/Optional	Description	Example
Senders	Required	The sender email addresses to block.	JSON `[ "test@example.com", "test@testsender.com" ]`
Recipients	Required	The recipients.	JSON `[ "user@example3.com", "user2@example4.com" ]`

Output

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

Error Handling

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

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

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Block Email Addresses 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 Cisco Email Security portal. Refer to the HTTP Status Code Registry for details.	Status Code: 500.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: The application raised an exception

Error Sample Data

Block Email Addresses failed.

Status Code: 500.

Message: The application raised an exception

Delete Entries

Deletes Safelist or Blocklist Entries from the spam quarantine.

Input

Input Parameter	Required/Optional	Description	Example
View By	Required	The reviewer of the entries. Valid options are: Sender Recipient	Sender
Recipient List	Required	The recipient list of the entries. This parameter is required when View By is set to Recipient.	JSON `[ "test1@example.com", "test2@example.com" ]`
Sender List	Required	The sender list of the entries. This parameter is required when View By is set to Sender.	JSON `[ "test@example.com", "test@testsender.com" ]`

Output

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

Error Handling

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

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

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Delete Entries 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 Cisco Email Security portal. Refer to the HTTP Status Code Registry for details.	Status Code: 500.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Server got itself in trouble: The application raised an exception.

Error Sample Data

Delete Entries failed.

Status Code: 500.

Message: Server got itself in trouble: The application raised an exception.

Delete Spam Quarantine Messages

Deletes messages from the spam quarantine.

READER NOTE

Quarantine Message IDs is a required parameter to run this command.

Run the Search Spam Quarantine Messages command to obtain the Quarantine Message IDs. Quarantine Message IDs can be found in the raw data at $.data[*].mid.

Input

Input Parameter	Required/Optional	Description	Example
Quarantine Message IDs	Required	The IDs of the messages to delete from the spam quarantine. Quarantine Message IDs can be obtained using the Search Spam Quarantine Messages command.	JSON `[ ***** ]`

Output

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

Error Handling

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

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

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Delete Spam Quarantine Messages failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Cisco Email Security 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: Message ID Not Found.

Error Sample Data

Delete Spam Quarantine Messages failed.

Status Code: 404.

Message: Message ID Not Found.

Fetch Event

Retrieves email messages from Cisco ESA.

Input

Input Parameter	Required/Optional	Description	Example
Messages Source	Required	The source of the messages to fetch. Valid options are: Message Tracking Spam Quarantine	Spam Quarantine
Start Time	Required	The start of the time range (in UTC) used to retrieve messages.	2023-04-24 00:00
End Time	Required	The end of the time range (in UTC) used to retrieve messages.	2023-04-26 00:00
Offset	Optional	The value indicating the position within the subset of records to begin fetching data. If Offset is defined, then Limit must also be defined. By default, the value is 0.	0
Limit	Optional	The maximum number of records to retrieve. If Limit is defined, then Offset must also be defined. For the Message Tracking Message Source, allowed values are integers between 1 and 100. For the Spam Quarantine Message Source, allowed values are integers between 1 and 250.	10

Output

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

Fetch Event Field Mapping

See Field Mappings.

The Cisco Email Security system integration includes pre-configured field mappings for the default event source.

The Default Event Source is the default system-provided set of field mappings applied when the fetch event command is executed. It includes a Main Event JSON Path, which is the JSONPath expression that points to the base array of event objects. The source field path continues from this array to locate the required data.

The Main Event JSON Path can be viewed by clicking on the Edit Event Source button.

Main Event JSON Path: $.data
The data array contains the event objects. For example, within each Message Tracking event object, the key attributes.mid[0] denotes the Document ID field. As such, the full JSONPath expression to extract the Document ID is $.data.attributes.mid[0].
Event Source for Message Tracking
The D3 system configures the field mappings which are specific to the message-tracking-related events. If a source field in the field mapping is not found, the corresponding field mapping will be ignored. Because the sourceType field in the raw data for Message Tracking events consistently has the value messageTracking, these events can be identified by the Search String: {$.sourceType}=messageTracking. Click Edit Event Source to view the Search String.

Event Source for Spam Quarantine
The D3 system configures the field mappings which are specific to the spam-quarantine-related events. If a source field in the field mapping is not found, the corresponding field mapping will be ignored. Because the sourceType field in the raw data for Spam Quarantine events consistently has the value spamQuarantine, these events can be identified by the Search String: {$.sourceType}=spamQuarantine. Click Edit Event Source to view the Search String.

The pre-configured field mappings are detailed below:

Field Name	Source Field
Default Event Source (Main Event JSON Path: $.data)
N/A
Event Source for Message Tracking (Search String: {$.sourceType}=messageTracking) The search string format is {jsonpath}=value. If the value of the sourceType key is messageTracking in the event object under raw data, then the Message Tracking related events will use the field mapping below.
Document ID	.attributes.mid[0]
Message ID	.attributes.mid[0]
Sender	.attributes.sender
Host Name	.attributes.hostName
Sender IP	.attributes.senderIp
Direction	.attributes.direction
Subject	.attributes.subject
Message Status	.attributes.messageStatus
Mail Policy	.attributes.mailPolicy[*]
Serial Number	.attributes.serialNumber
Recipient	.attributes.recipient[*]
TimeStamp	.attributes.timestamp
Event Source for Spam Quarantine (Search String: {$.sourceType}=spamQuarantine) The search string format is {jsonpath}=value. If the value of the sourceType key is spamQuarantine in the event object under raw data, then the Spam Quarantine related events will use the field mapping below.
Document ID	.mid
Message ID	.mid
Date	.attributes.date
Envelope Recipient	.attributes.envelopeRecipient
To Address	.attributes.toAddress[*]
From Address	.attributes.fromAddress[*]
Subject	.attributes.subject
Date	.attributes.date

Error Handling

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

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

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Fetch Event failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Cisco Email Security 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: Bad request.

Error Sample Data

Fetch Event failed.

Status Code: 400.

Message: Bad request.

Get AMP Details

Retrieves Advanced Malware Protection details of messages.

READER NOTE

Appliance Serial Number and Message IDs are required parameters to run this command.

Run the Search Messages command to obtain the Appliance Serial Number. Appliance Serial Numbers can be found in the raw data at $.data[*].attributes.serialNumber.
Run the Search Messages command to obtain the Message IDs. Message IDs can be found in the raw data at $.data[*].attributes.mid.

Injection Connection ID is an optional parameter to run this command.

Run the Search Messages command to obtain the Injection Connection ID. Injection Connection IDs can be found in the raw data at $.data[*].attributes.icid.

Input

Input Parameter	Required/Optional	Description	Example
Appliance Serial Number	Required	The appliance serial number used to retrieve AMP details. Appliance Serial Number can be obtained using the Search Messages command.	6412*****V1ST
Message IDs	Required	The IDs of the messages used to retrieve AMP details. Message IDs can be obtained using the Search Messages command.	JSON `[ ***** ]`
Injection Connection ID	Optional	The Injection Connection ID of the messages used to retrieve AMP details. Injection Connection ID can be obtained using the Search Messages command.	*****

Output

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

Error Handling

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

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

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get AMP Details 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 Cisco Email Security 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: Message ID Not Found.

Error Sample Data

Get AMP Details failed.

Status Code: 404.

Message: Message ID Not Found.

Get DLP Details

Retrieves Data Loss Prevention details of messages.

READER NOTE

Appliance Serial Number and Message IDs are required parameters to run this command.

Run the Search Messages command to obtain the Appliance Serial Number. Appliance Serial Numbers can be found in the raw data at $.data[*].attributes.serialNumber.
Run the Search Messages command to obtain the Message IDs. Message IDs can be found in the raw data at $.data[*].attributes.mid.

Injection Connection ID is an optional parameter to run this command.

Run the Search Messages command to obtain the Injection Connection ID. Injection Connection IDs can be found in the raw data at $.data[*].attributes.icid.

Input

Input Parameter	Required/Optional	Description	Example
Appliance Serial Number	Required	The appliance serial number used to retrieve DLP details. Appliance Serial Number can be obtained using the Search Messages command.	6412*****V1ST
Message IDs	Required	The IDs of the messages used to retrieve DLP details. Message IDs can be obtained using the Search Messages command.	JSON `[ ***** ]`
Injection Connection ID	Optional	The Injection Connection ID of the messages used to retrieve DLP details. Injection Connection ID can be obtained using the Search Messages command.	*****

Output

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

Error Handling

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

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

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get DLP Details 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 Cisco Email Security 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: Message ID Not Found.

Error Sample Data

Get DLP Details failed.

Status Code: 404.

Message: Message ID Not Found.

Get Message Details

Retrieves details of the specified messages.

READER NOTE

Appliance Serial Number and Message IDs are required parameters to run this command.

Run the Search Messages command to obtain the Appliance Serial Number. Appliance Serial Numbers can be found in the raw data at $.data[*].attributes.serialNumber.
Run the Search Messages command to obtain the Message IDs. Message IDs can be found in the raw data at $.data[*].attributes.mid.

Injection Connection ID is an optional parameter to run this command.

Run the Search Messages command to obtain the Injection Connection ID. Injection Connection IDs can be found in the raw data at $.data[*].attributes.icid.

Input

Input Parameter	Required/Optional	Description	Example
Appliance Serial Number	Required	The appliance serial number used to retrieve message details. Appliance Serial Number can be obtained using the Search Messages command.	6412*****V1ST
Message IDs	Required	The IDs of the messages used to retrieve message details. Message IDs can be obtained using the Search Messages command.	JSON `[ ***** ]`
Injection Connection ID	Optional	The Injection Connection ID of the messages used to retrieve message details. Injection Connection ID can be obtained using the Search Messages command.	*****

Output

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

Error Handling

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

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

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Message Details 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 Cisco Email Security portal. Refer to the HTTP Status Code Registry for details.	Status Code: 500.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Server got itself in trouble: The application raised an exception.

Error Sample Data

Get Message Details failed.

Status Code: 500.

Message: Server got itself in trouble: The application raised an exception.

Get Report

Retrieves data from reports.

Input

Input Parameter	Required/Optional	Description	Example
Counter Group	Optional	The counter group from which to fetch data. By default, the value is set to mail_incoming_traffic_summary.	mail_policy_incoming
Counter	Optional	The counter name within the specified counter group to retrieve. By default, all counters in the group are retrieved.	recipients_matched
Start Time	Required	The start date and time of the report query (in UTC) . The minutes (mm) and seconds (ss) values must be set to 00.	2023-05-20T18:00:00Z
End Time	Required	The end date and time of the report query (in UTC). The minutes (mm) and seconds (ss) values must be set to 00.	2023-05-21T18:00:00Z
Order By	Optional	The attribute used to order the data in the response. Not all counter groups support this parameter. Download the Cisco AsyncOS API Addendum for details.	recipients_matched
Order Direction	Optional	The sort direction. By default, the value is set to Descending.	Descending
Filter By	Optional	The field used to filter results. Not all counter groups support this parameter. Download the Cisco AsyncOS API Addendum for details.	ip_address
Filter Operator	Optional	The filter operator. By default, the value is set to Begins With.	IS
Filter Value	Optional	The value that corresponds to the field specified in the Filter By parameter.	10.0.0
Top	Optional	The maximum number of records with the highest values to return. This parameter is only applied if Counter is defined. Not all counter groups support this parameter. Download the Cisco AsyncOS API Addendum for details.	10

Output

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

Error Handling

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

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

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Report 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 Cisco Email Security portal. Refer to the HTTP Status Code Registry for details.	Status Code: 500.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Server got itself in trouble: The application raised an exception.

Error Sample Data

Get Report failed.

Status Code: 500.

Message: Server got itself in trouble: The application raised an exception.

Get Spam Quarantine Message Details

Retrieves details of the specified spam quarantine messages.

READER NOTE

Quarantine Message IDs is a required parameter to run this command.

Run the Search Spam Quarantine Messages command to obtain the Quarantine Message IDs. Quarantine Message IDs can be found in the raw data at $.data[*].mid.

Input

Input Parameter	Required/Optional	Description	Example
Quarantine Message IDs	Required	The IDs of the messages used to retrieve quarantine message details. Quarantine Message IDs can be obtained using the Search Spam Quarantine Messages command.	JSON `[ ***** ]`

Output

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

Error Handling

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

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

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get Spam Quarantine Message Details 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 Cisco Email Security portal. Refer to the HTTP Status Code Registry for details.	Status Code: 500.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Server got itself in trouble: The application raised an exception.

Error Sample Data

Get Spam Quarantine Message Details failed.

Status Code: 500.

Message: Server got itself in trouble: The application raised an exception.

Get URL Details

Retrieves the URL details of the specified messages.

READER NOTE

Appliance Serial Number and Message IDs are required parameters to run this command.

Run the Search Messages command to obtain the Appliance Serial Number. Appliance Serial Numbers can be found in the raw data at $.data[*].attributes.serialNumber.
Run the Search Messages command to obtain the Message IDs. Message IDs can be found in the raw data at $.data[*].attributes.mid.

Injection Connection ID is an optional parameter to run this command.

Run the Search Messages command to obtain the Injection Connection ID. Injection Connection IDs can be found in the raw data at $.data[*].attributes.icid.

Input

Input Parameter	Required/Optional	Description	Example
Appliance Serial Number	Required	The appliance serial number used to retrieve URL details. Appliance Serial Number can be obtained using the Search Messages command.	6412*****V1ST
Message IDs	Required	The IDs of the messages used to retrieve URL details. Message IDs can be obtained using the Search Messages command.	JSON `[ ***** ]`
Injection Connection ID	Optional	The Injection Connection ID of the messages used to retrieve URL details. Injection Connection ID can be obtained using the Search Messages command.	*****

Output

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

Error Handling

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

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

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Get URL Details 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 Cisco Email Security portal. Refer to the HTTP Status Code Registry for details.	Status Code: 500.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Server got itself in trouble: The application raised an exception.

Error Sample Data

Get URL Details failed.

Status Code: 500.

Message: Server got itself in trouble: The application raised an exception.

Release Spam Quarantine Messages

Releases the specified spam quarantine messages.

READER NOTE

Quarantine Message IDs is a required parameter to run this command.

Run the Search Spam Quarantine Messages command to obtain the Quarantine Message IDs. Quarantine Message IDs can be found in the raw data at $.data[*].mid.

Input

Input Parameter	Required/Optional	Description	Example
Quarantine Message IDs	Required	The IDs of the quarantine messages to release. Quarantine Message IDs can be obtained using the Search Spam Quarantine Messages command.	JSON `[ ***** ]`

Output

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

Error Handling

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

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

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Release Spam Quarantine Messages failed.
Status Code	The response code issued by the third-party API server or the D3 SOAR system that can be used to locate the corresponding error category. For example, if the returned status code is 401, the selected connection is unauthorized to run the command. The user or system support would need to check the permission setting in the Cisco Email Security 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: Message ID not found.

Error Sample Data

Release Spam Quarantine Messages failed.

Status Code: 404.

Message: Message ID not found.

Search List Entries

Retrieves safelist or blocklist entries using API queries. Returned entries are sorted alphabetically by recipient or sender address.

Input

Input Parameter	Required/Optional	Description	Example
List Type	Required	The type of list to retrieve. Valid options are: Blocklist Safelist	Blocklist
View By	Required	Filters list entries by recipient view or sender view. Valid options are: Sender Recipient	Recipient
Sender Name	Optional	Filters list entries by a partial or full sender name when viewing by recipient. This parameter is applicable only when View By is set to Recipient.	John

Output

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

Error Handling

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

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

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Search List Entries 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 Cisco Email Security portal. Refer to the HTTP Status Code Registry for details.	Status Code: 500.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Server got itself in trouble: The application raised an exception.

Error Sample Data

Search List Entries failed.

Status Code: 500.

Message: Server got itself in trouble: The application raised an exception.

Search Messages

Retrieves tracking messages that match the specified filter parameters.

Input

Input Parameter	Required/Optional	Description	Example
Start Time	Required	The start date and time of the search range (in UTC).	2023-05-20T18:00:00Z
End Time	Required	The end date and time of the search range (in UTC).	2023-05-21T18:00:00Z
Subject	Optional	The full or partial subject line of the message to search.	test
Sender	Optional	The full or partial sender email address of the message to search.	actor@example.com
Recipient	Optional	The full or partial recipient email address of the message to search.	user1@example.com
File SHA256	Optional	The SHA-256 hash value of an attached file to search.	af77*****767e
Attachment Name	Optional	The full or partial file name of the message attachment to search.	bonus
Internet Message ID	Optional	The internet message ID of the message to search.	<2018***1969@*.***>
Additional Filters	Optional	Additional message filters to use. Multiple filters must be combined with an ampersand (&). Download the Cisco AsyncOS API Addendum for the list of supported filter attributes.	senderIp=192.0.2.10 & deliveryStatus=DELIVERED

Output

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

Error Handling

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

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

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

Error Sample Data

Search Messages failed.

Status Code: 500.

Message: Server got itself in trouble: The application raised an exception.

Search Spam Quarantine Messages

Retrieves messages from the spam quarantine that match the specified filter parameters.

Input

Input Parameter	Required/Optional	Description	Example
Start Time	Required	The start date and time of the search range (in UTC).	2023-05-20T18:00:00Z
End Time	Required	The end date and time of the search range (in UTC).	2023-05-21T18:00:00Z
Recipient	Optional	The full or partial recipient email address to search in the spam quarantine.	test@test.com
Filter By	Optional	The message attribute used to filter spam quarantine messages. Valid options are: From_Address To_Address Subject By default, the value is set to Subject.	From_Address
Filter Operator	Optional	The operator applied to the filter. Valid options are: Contains Is Begins_With Ends_With Does_Not_Contain By default, the value is set to Contains.	IS
Filter Value	Optional	The value that corresponds to the field specified in Filter By.	danel

Output

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

Error Handling

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

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

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

Error Sample Data

Search Spam Quarantine Messages failed.

Status Code: 500.

Message: Server got itself in trouble: The application raised an exception.

Unblock Domains or Email Addresses

Removes specified domains or email addresses from the sender or recipient block list.

Input

Input Parameter

Required/Optional

Description

Example

Block List Type

Optional

The type of block list from which to remove entries. Valid options are:

Sender Block List
Recipient Block List

By default, the value is set to Sender Block List.

Sender Block List

Domains or Email Addresses

Required

The domains and/or email addresses to remove from the specified block list.

JSON

[
  "example.com",
  "user@example.com"
]

Output

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

Error Handling

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

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

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	Unblock Domains or Email Addresses 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 Cisco Email Security 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: Bad request.

Error Sample Data

Unblock Domains or Email Addresses failed.

Status Code: 400.

Message: Bad request.

Test Connection

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

Input

N/A

Output

Output Type

Description

Return Data Type

Return Data

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

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

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

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

String

Error Handling

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

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

Parts in Error	Description	Example
Failure Indicator	Indicates the command failure that happened at a specific input and/or API call.	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 Cisco Email Security portal. Refer to the HTTP Status Code Registry for details.	Status Code: 500.
Message	The raw data or captured key error message from the integration API server about the API request failure.	Message: Server got itself in trouble: The application raised an exception.

Error Sample Data

Test Connection failed. Failed to check the connector.

Status Code: 500.

Message: Server got itself in trouble: The application raised an exception.