AsyncOS 13.5.

1 API for Cisco Email Security Appliances - Getting

Started Guide - GD (General Deployment)
First Published: 2020-06-02

Americas Headquarters
Cisco Systems, Inc.
170 West Tasman Drive
San Jose, CA 95134-1706
USA
http://www.cisco.com
Tel: 408 526-4000
800 553-NETS (6387)
Fax: 408 527-0883
THE SPECIFICATIONS AND INFORMATION REGARDING THE PRODUCTS IN THIS MANUAL ARE SUBJECT TO CHANGE WITHOUT NOTICE. ALL STATEMENTS,
INFORMATION, AND RECOMMENDATIONS IN THIS MANUAL ARE BELIEVED TO BE ACCURATE BUT ARE PRESENTED WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED. USERS MUST TAKE FULL RESPONSIBILITY FOR THEIR APPLICATION OF ANY PRODUCTS.

THE SOFTWARE LICENSE AND LIMITED WARRANTY FOR THE ACCOMPANYING PRODUCT ARE SET FORTH IN THE INFORMATION PACKET THAT SHIPPED WITH
THE PRODUCT AND ARE INCORPORATED HEREIN BY THIS REFERENCE. IF YOU ARE UNABLE TO LOCATE THE SOFTWARE LICENSE OR LIMITED WARRANTY,
CONTACT YOUR CISCO REPRESENTATIVE FOR A COPY.

The Cisco implementation of TCP header compression is an adaptation of a program developed by the University of California, Berkeley (UCB) as part of UCB's public domain version of
the UNIX operating system. All rights reserved. Copyright © 1981, Regents of the University of California.

NOTWITHSTANDING ANY OTHER WARRANTY HEREIN, ALL DOCUMENT FILES AND SOFTWARE OF THESE SUPPLIERS ARE PROVIDED “AS IS" WITH ALL FAULTS.
CISCO AND THE ABOVE-NAMED SUPPLIERS DISCLAIM ALL WARRANTIES, EXPRESSED OR IMPLIED, INCLUDING, WITHOUT LIMITATION, THOSE OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OR ARISING FROM A COURSE OF DEALING, USAGE, OR TRADE PRACTICE.

IN NO EVENT SHALL CISCO OR ITS SUPPLIERS BE LIABLE FOR ANY INDIRECT, SPECIAL, CONSEQUENTIAL, OR INCIDENTAL DAMAGES, INCLUDING, WITHOUT
LIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THIS MANUAL, EVEN IF CISCO OR ITS SUPPLIERS
HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Any Internet Protocol (IP) addresses and phone numbers used in this document are not intended to be actual addresses and phone numbers. Any examples, command display output, network
topology diagrams, and other figures included in the document are shown for illustrative purposes only. Any use of actual IP addresses or phone numbers in illustrative content is unintentional
and coincidental.

All printed copies and duplicate soft copies of this document are considered uncontrolled. See the current online version for the latest version.

Cisco has more than 200 offices worldwide. Addresses and phone numbers are listed on the Cisco website at www.cisco.com/go/offices.

Cisco and the Cisco logo are trademarks or registered trademarks of Cisco and/or its affiliates in the U.S. and other countries. To view a list of Cisco trademarks, go to this URL:
https://www.cisco.com/c/en/us/about/legal/trademarks.html. Third-party trademarks mentioned are the property of their respective owners. The use of the word partner does not imply a
partnership relationship between Cisco and any other company. (1721R)
© 2020 Cisco Systems, Inc. All rights reserved.
 CONTENTS

CHAPTER 1 Overview of AsyncOS API for Cisco Email Security Appliances 1

Prerequisites for Using AsyncOS API 1

Enabling AsyncOS API 2
Securely Communicating with AsyncOS API 2
AsyncOS API Authentication and Authorization 3
Authentication 3
Authenticating API Queries with JSON Web Token 3
Authorization 4
AsyncOS API Requests and Responses 5
AsyncOS API Requests 5
AsyncOS API Responses 6
Key Components of Responses 6
HTTP Response Codes 7
AsyncOS API Capabilities 8

CHAPTER 2 APIs for Email 9

Reporting APIs 9
Examples 11
Retrieving a Single Value for a Counter 12
Retrieving Multiple Values for a Counter 12
Retrieving Single Values for Each Counter in a Counter Group 13
Retrieving Multiple Values for Multiple Counters 14
Retrieving Multiple Values for Multiple Counters, with Multiple Values for Each Counter 16
Tracking APIs 18
Searching for Messages 18
Rejected Connections 23

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
iii
 Contents

Message Details 24
DLP Details 27
AMP Details 28
URL Details 30
Connection Details 32
Remediation Details 34
Quarantine 35
APIs for Spam Quarantine 36
Searching for Messages 36
Retrieving Message Details 39
Deleting Messages 41
Releasing Messages 42
Searching for Safelist and Blocklist Entries 43
Adding, Editing, and Appending Safelist and Blocklist Entries 46
Deleting Safelist or Blocklist Entries 59
APIs for Other Quarantine 63
Searching for Messages 63
Retrieving Message Details 70
Move Messages 72
Delaying the Exit of a Message from a Quarantine 73

Sending a Copy of a Message in Quarantine 75

Downloading an Attachment 77
Deleting Messages 78
Releasing Messages 79
Viewing the Rule Summary 81
Searching Based on Rule ID 82
Releasing Messages from the Rule Summary 85
Deleting Messages from the Rule Summary 86

CHAPTER 3 General Purpose APIs 89

Querying for the System Time 89

Querying for Managed Email Security Appliances' Information 90
Retrieving APIs Accessible to a User Role 90
Health API 91

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
iv
 Contents

CHAPTER 4 Troubleshooting AsyncOS API 97

API Logs 97
Alerts 97

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
v
Contents

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
vi
 CHAPTER 1
Overview of AsyncOS API for Cisco Email
Security Appliances
The AsyncOS API for Cisco Email Security appliances (or AsyncOS API) is a representational state transfer
(REST) based set of operations that provide secure and authenticated access to the Email Security appliance
reports, report counters, and tracking. You can retrieve the Email Security appliance reporting and tracking
data using the API. In this release you can query for configuration information. Posting configuration changes
is not supported in this release.
For more information, refer to the Swagger API help. To view the API help, access the new web interface of
the appliance, click the help icon on the top right corner of the page and select API Help: Swagger.
This chapter contains the following sections:
• Prerequisites for Using AsyncOS API, on page 1
• Enabling AsyncOS API, on page 2
• Securely Communicating with AsyncOS API, on page 2
• AsyncOS API Authentication and Authorization, on page 3
• AsyncOS API Requests and Responses, on page 5
• AsyncOS API Capabilities, on page 8

Prerequisites for Using AsyncOS API

To use AsyncOS API, you need the knowledge of:
• • HTTP, which is the protocol used for API transactions. Secure communication over TLS.
• JavaScript Object Notation (JSON), which the API uses to construct resource representations.
• JSON Web Token (JWT)

• A client or programming library that initiates requests and receives responses from the AsyncOS API
using HTTP or HTTPS, for example, cURL. The client or programming library must support JSON to
interpret the response from the API.
• Authorization to access the AsyncOS API. See Authorization, on page 4.
• AsyncOS API enabled using web interface or CLI. See Enabling AsyncOS API, on page 2.

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
1
 Overview of AsyncOS API for Cisco Email Security Appliances
Enabling AsyncOS API

Note Version 1.0 APIs are not supported from Cisco Email Security 13.0 release and later. Instead version 2.0 APIs
are used.

Enabling AsyncOS API

Before You Begin
Make sure that you are authorized to access the IP Interfaces page on the web interface or the interfaceconfig
command on CLI. Only administrators, email administrators, cloud administrators, and operators are authorized.
You can also enable the AsyncOS API using the interfaceconfig command in CLI.

Step 1 Log in to the web interface.

Step 2 Choose Network > IP Interfaces.
Step 3 Edit the Management interface.
Note • You can enable AsyncOS API on any IP interface. However, Cisco recommends that you enable AsyncOS
API on the Management interface.
• You must not enable APIs on multiple management interface.

Step 4 Under the AsyncOS API (Monitoring) section, depending on your requirements, select HTTP, HTTPS, or both and the
ports to use.
Note AsyncOS API communicates using HTTP / 1.1.
If you have selected HTTPS and you want to use your own certificate for secure communication, see Securely
Communicating with AsyncOS API, on page 2.
Note Cisco recommends that you always use HTTPS in the production environment. Use HTTP only for
troubleshooting and testing the API.

Step 5 Submit and commit your changes.

Securely Communicating with AsyncOS API

You can communicate with AsyncOS API over secure HTTP using your own certificate.

Note Do not perform this procedure if you are already running the web interface over HTTPS and using your own
certificate for secure communication. AsyncOS API uses the same certificate as web interface, for
communicating over HTTPS.

Step 1 Set up a certificate using the certconfig command in the CLI. For instructions, refer the User Guide or Online Help.

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
2
 Overview of AsyncOS API for Cisco Email Security Appliances
AsyncOS API Authentication and Authorization

Step 2 Change the HTTPS certificate used by the IP interface to your certificate using the interfaceconfig command in CLI.
For instructions, refer the User Guide or Online Help.
Step 3 Submit and commit your changes.

AsyncOS API Authentication and Authorization

This section explains about the authentication methods, the user roles which can access APIs, and how to
query for APIs accessible to a user.
• Authentication, on page 3
• Authorization, on page 4
• Retrieving APIs Accessible to a User Role, on page 90

Authentication
Submit the Cisco Email Security appliance's username and password with all the requests to the API, in the
Base64-encoded format or with a JSON Web Token. The user inactivity timeout settings in the appliance
apply to the validity of a JWT. If a request does not include valid credentials in the Authorization header, the
API sends a 401 error message. You can use any base64 library to convert your credentials into base64-encoded
format. You can authenticate queries to the API using either of the following two methods:

Authenticating API Queries with JSON Web Token

You can generate a JSON Web Token (JWT) and use it with your API queries.

Note The user inactivity timeout settings in the appliance applies to the validity of a JWT. The appliance checks
every API query with a JWT, for its time validity. If a JWT is found to be within 5 minutes of time validity,
after which it will time out, a new refresh JWT is sent with the response header. You must use this new refresh
JWT with API queries, or generate a new one.

Synopsis POST /esa/api/v2.0/login

Use the syntax below for two factor authentications:

POST /esa/api/v2.0/login/two_factor

Body Use Base64 encoded credentials.

Parameters {
"data":
{
"userName":"YWRtaW4=",
"passphrase":"aXJvbnBvcnQ="
}
}

Request Host, Accept, Authorization

Headers

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
3
 Overview of AsyncOS API for Cisco Email Security Appliances
Authorization

Response Content-Type, Content-Length, Connection

Headers

This example shows a query to log in with Base64 encoded credentials, and generate a JWT.
Sample Request
POST /esa/api/v2.0/login
HTTP/1.1
Content-Type: application/json
cache-control: no-cache
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
content-length: 95
Connection: keep-alive
{
"data":
{
"userName":"YWRtaW4=",
"passphrase":"aXJvbnBvcnQ="
}
}

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Mon, 26 Nov 2018 07:22:47 GMT
Content-type: application/json
Content-Length: 618
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"data": {
"userName": "admin",
"is2FactorRedirectRequired": "false",
"role": "Administrator",
"email": [],
"jwtToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyTmFtZSI6ImFkbWluIiwiaXM
yRmFjdG9yQ2hlY2tSZXF1aXJlZCI6ZmFsc2UsImNvb2tpZSI6IlRucEZOVTFFWTNwTlZFMDlDanRMYVR
oeENqdFpiV1J6VFVSQk5VMURNWGRpTWxGMVdUSnNlbGt5T0hWWk1qbDBUMnBaZDA5RVFUMEtcbk8xVkh
PWHBrUnpGb1lteEtNV0p1VW5CaVYxVjJUbmswTUV4cVFUMEtPMVJVUlhkTlJsazNUVlJKZFUxRE5IZE1
WRWw1VFdwek1FMXFcblNUVlNhazVDVDBWRk1rOUVaM2xTUlVreVRYcGtSazFwTVVSTlZFMHpUbFZXUjA1
}
}

Authorization
The AsyncOS API is a role based system, the scope of API queries is defined by the role of the user. Cisco
Email Security appliance users with the following roles can access the AsyncOS API:
• Administrator
• Operator

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
4
 Overview of AsyncOS API for Cisco Email Security Appliances
AsyncOS API Requests and Responses

• Technician
• Read-Only Operator
• Guest
• URL Filtering Administrator
• Email Administrator
• Help Desk User

Note • Externally authenticated users can access the API.

• Custom roles, delegated by the administrator can also access the APIs.

AsyncOS API Requests and Responses

• AsyncOS API Requests, on page 5
• AsyncOS API Responses, on page 6

AsyncOS API Requests

Requests made to the API have the following characteristics:
• Requests are sent over HTTP or HTTPS
• Each request must contain a valid URI in the following format:
http://{appliance}:{port}/esa/api/v2.0/{resource}/{resource_attributes}
https://{appliance}:{port}/esa/api/v2.0/{resource}/{resource_attributes}

where:
• {appliance}:{port}
is the FQDN or the IP address of the appliance and the TCP port number on which the appliance is
listening.
• {resource}
is the resource you are attempting to access, for example, reports, tracking, quarantine, configuration,
or other counters.
• {resource_attributes}
are the supported attributes for a resource, for example, duration, and so on.
• Each request must contain user credentials, or a valid authorization header.
• Each request must be set to accept:
application/json

• Requests sent over HTTPS (using your own certificate) must contain your CA certificate. For example,
in case of cURL, you can specify the CA certificate in the API request as follows:

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
5
 Overview of AsyncOS API for Cisco Email Security Appliances
AsyncOS API Responses

curl --cacert <ca_cert.crt> -u"username:password"

https://<fqdn>:<port>/esa/api/v2.0/{resource}/{resource_attributes}

Note API requests are case sensitive and should be entered as shown in this guide.

AsyncOS API Responses

This section explains the key components of the responses, and various HTTP error codes.
• Key Components of Responses, on page 6
• HTTP Response Codes, on page 7

Key Components of Responses

Components Values Description

Status Code and Reason See HTTP Response HTTP response code and the reason.
Codes, on page 7.

Message Content-Type application/json Indicates the format of the message body.

Header
Content-Length n/a The length of the response body in octets.

Connection close Options that are desired for the connection.

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
6
 Overview of AsyncOS API for Cisco Email Security Appliances
HTTP Response Codes

Components Values Description

Message Body n/a The message body is in the format defined by the
Content-Type header. The following are the
components of the message body:
1. URI. The URI you specified in the request to the
API.
Example
:"/api/v2.0/config/"

2. Counter group and/or counter name

Example
reporting/mail_security_summary

3. Query parameters
Example
startDate=2017-01-30T00:00:00.000Z&endDate=2018-01-
30T14:00:00.000Z

4. Error (Only for Error Events). This component

includes three subcomponents—message, code,
and explanation.
Example
"error": {"message": "Unexpected attribute

- starts_with.","code": "404",
"explanation":
"404 = Nothing matches the given URI."}

If the message body contains empty braces ({}),

it means that the API could not find any records
matching the query.

HTTP Response Codes

The following is a list of HTTP response codes returned by AsyncOS API:
• 200
• 202
• 300
• 301
• 307
• 400
• 401
• 403
• 404

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
7
 Overview of AsyncOS API for Cisco Email Security Appliances
AsyncOS API Capabilities

• 406
• 413
• 414
• 500
• 501
• 503
• 505
For descriptions of these HTTP response codes, refer the following RFCs:
• RFC1945
• RFC7231

AsyncOS API Capabilities

You can use the AsyncOS API to retrieve information in the following categories:
• APIs for Email, on page 9
• General Purpose APIs, on page 89

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
8
 CHAPTER 2
APIs for Email
• Reporting APIs, on page 9
• Tracking APIs, on page 18
• Quarantine, on page 35

Reporting APIs
Reporting queries can be used to fetch data from reports, for all counters under a specific group, or for a
specific counter.

Synopsis GET /api/v2.0/reporting/report?resource_attribute

GET /api/v2.0/reporting/report/counter?resource_attribute

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
9
 APIs for Email
Reporting APIs

Supported Duration This is a required parameter. All API queries should be accompanied with this
Resource parameter.
Attributes startdate=YYYY-MM-DDThh:mm:00.000Z&endDate=YYYY-MM-DDThh:mm:00.000Z

Aggregate report(s) for the specified duration.

Query Type • query_type=graph

Receive data that can be represented as graphs.
• query_type=export
Receive data in the export format.

Sorting You should use both these parameters. If you use either, you will not receive
data in the response.
• orderBy=<value>
Specify the attribute by which to order the data in the response. For
example,
orderBy=total_clean_recipients

• orderDir=<value>
Specify sort direction.
The valid options are:
• asc
Order the results in ascending order.
• desc
Order the results in descending order.

Lazy You should use both these parameters. If you use either, you will not receive
Loading data in the response.
• offset=<value>
Specify an offset value to retrieve a subset of records starting with the
offset value. Offset works with limit, which determines how many records
to retrieve starting from the offset.
• limit=<value>
Specify the number of records to retrieve.

Data • top=<value>
Retrieval
Specify the number of records with the highest values to return.
Option

Filtering

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
10
 APIs for Email
Examples

Filter parameters restrict the data to be included the response.

• filterValue=<value>
The value to search for.
• filterBy=<value>
Filter the data to be retrieved according to the filter property and value.
• filterOperator=<value>
The valid options are:
• begins_with
Filter the response data based on the value specified. This is not an
exact value.
• is
Filter the response data based on the exact value specified.

Device • device_group_name=<value>
Specify the device group name.
• device_type=esa
Specify the device type. This is a required parameter. All API queries must
be accompanied with this parameter.
• device_name=<value>
Specify the device name.

Request Host, Accept, Authorization

Headers

Response Content-Type, Content-Length, Connection

Headers

Examples
Examples for the types of reporting queries are shown below:
• Retrieving a Single Value for a Counter, on page 12
• Retrieving Multiple Values for a Counter, on page 12
• Retrieving Single Values for Each Counter in a Counter Group, on page 13
• Retrieving Multiple Values for Multiple Counters, on page 14
• Retrieving Multiple Values for Multiple Counters, with Multiple Values for Each Counter, on page 16

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
11
 APIs for Email
Retrieving a Single Value for a Counter

Retrieving a Single Value for a Counter

This example shows a query to retrieve the value of a specific counter from a counter group, with the device
name and type.
Sample Request
GET /esa/api/v2.0/reporting/mail_incoming_traffic_summary/detected_amp?
startDate=2016-09-10T19:00:00.000Z&endDate=2018-09-24T23:00:00.000Z
HTTP/1.1
cache-control: no-cache
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
Connection: keep-alive

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Sat, 17 Nov 2018 15:58:29 GMT
Content-type: application/json
Content-Length: 96
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"meta": {
"totalCount": -1},
"data": {
"type": "detected_amp",
"resultSet": {
"detected_amp": 11}
}
}

Retrieving Multiple Values for a Counter

This example shows a query to retrieve values of all counters of a counter group, with the device group name
and device type.
Sample Request
GET /esa/api/v2.0/reporting/mail_incoming_traffic_summary?startDate=2016
-09-10T19:00:00.000Z&endDate=2018-09-24T23:00:00.000Z&device_type=esa
HTTP/1.1
cache-control: no-cache
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
Connection: keep-alive

Sample Response
HTTP/1.1 200 OK
Server: API/2.0

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
12
 APIs for Email
Retrieving Single Values for Each Counter in a Counter Group

Date: Sat, 17 Nov 2018 17:39:34 GMT

Content-type: application/json
Content-Length: 580
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{"meta": {"totalCount": -1}, "data":

{"type":
"mail_incoming_traffic_summary",
"resultSet": [{"verif_decrypt_success":5},
{"detected_virus": 13},
{"verif_decrypt_fail": 5},
{"threat_content_filter": 10},
{"total_graymail_recipients": 9},
{"blocked_invalid_recipient": 2},
{"ims_spam_increment_over_case": 0},
{"blocked_dmarc": 0},
{"marketing_mail": 6},
{"detected_amp": 2},
{"bulk_mail": 2},
{"total_recipients": 159},
{"social_mail": 1},
{"detected_spam": 30},
{"total_clean_recipients": 83},
{"malicious_url": 6},
{"total_threat_recipients": 67},
{"blocked_reputation": 10}]}}

Retrieving Single Values for Each Counter in a Counter Group

A counter group may have multiple counters. This example shows a query to retrieve single values for each
counter in a counter group, with order, device type and top parameters.
Sample Request
GET /esa/api/v2.0/reporting/mail_content_filter_incoming/recipients
_matched?startDate=2017-09-10T19:00:00.000Z&endDate=2018-09-24T23:00:00.000Z&device_type
=esa&orderDir=desc&orderBy=recipients_matched&top=2
HTTP/1.1
cache-control: no-cache
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
Connection: keep-alive

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Sat, 17 Nov 2018 18:17:29 GMT
Content-type: application/json
Content-Length: 153
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
13
 APIs for Email
Retrieving Multiple Values for Multiple Counters

{
"meta": {
"totalCount": -1
},
"data": {
"type": "recipients_matched",
"resultSet": {
"recipients_matched": [
{"url_rep_neutral": 16},
{"url_category": 8}
]
}
}
}

Retrieving Multiple Values for Multiple Counters

This example shows a query to retrieve multiple values for multiple counters, with offset, limit and device
type parameters.
Sample Request
GET /esa/api/v2.0/reporting/mail_incoming_domain_detail?startDate=2017-09-10T19:00:00.000Z
&endDate=2018-09-24T23:00:00.000Z&device_type=esa&offset=1&limit=2
HTTP/1.1
cache-control: no-cache
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
Connection: keep-alive

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Sat, 17 Nov 2018 18:25:28 GMT
Content-type: application/json
Content-Length: 1934
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"meta": {
"totalCount": -1
},
"data": {
"type": "mail_incoming_domain_detail",
"resultSet": {
"conn_tls_total": [
{"pphosted.com": 0},
{"vm30bsd0004.ibqa": 5}
],
"conn_tls_opt_success": [
{"pphosted.com": 0},
{"vm30bsd0004.ibqa": 0}
],
"conn_tls_opt_fail": [
{"pphosted.com": 0},

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
14
APIs for Email
Retrieving Multiple Values for Multiple Counters

{"vm30bsd0004.ibqa": 0}
],
"blocked_invalid_recipient": [
{"pphosted.com": 0},
{"vm30bsd0004.ibqa": 1}
],
"last_sender_group_name": [
{"pphosted.com": "UNKNOWNLIST"},
{"vm30bsd0004.ibqa": "UNKNOWNLIST"}
],
"detected_amp": [
{"pphosted.com": 0},
{"vm30bsd0004.ibqa": 2}
],
"social_mail": [
{"pphosted.com": 0},
{"vm30bsd0004.ibqa": 1}
],
"detected_spam": [
{"pphosted.com": 0},
{"vm30bsd0004.ibqa": 25}
],
"blocked_reputation": [
{"pphosted.com": 0},
{"vm30bsd0004.ibqa": 5}
],
"total_throttled_recipients": [
{"pphosted.com": 0},
{"vm30bsd0004.ibqa": 2}
],
"total_accepted_connections": [
{"pphosted.com": 2},
{"vm30bsd0004.ibqa": 119}
],...

...
"threat_content_filter": [
{"pphosted.com": 0},
{"vm30bsd0004.ibqa": 5}
],
"marketing_mail": [
{"pphosted.com": 0},
{"vm30bsd0004.ibqa": 5}
],
"blocked_dmarc": [
{"pphosted.com": 0},
{"vm30bsd0004.ibqa": 0}
],

"conn_tls_success": [
{"pphosted.com": 0},
{"vm30bsd0004.ibqa": 5}
],
"total_recipients": [
{"pphosted.com": 2},
{"vm30bsd0004.ibqa": 112}
],
"conn_tls_fail": [
{"pphosted.com": 0},
{"vm30bsd0004.ibqa": 0}
],
"total_threat_recipients": [
{"pphosted.com": 0},

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
15
 APIs for Email
Retrieving Multiple Values for Multiple Counters, with Multiple Values for Each Counter

{"vm30bsd0004.ibqa": 49}
]
}
}
}

Retrieving Multiple Values for Multiple Counters, with Multiple Values for Each Counter
This example shows a query to retrieve multiple values for multiple counters (with multiple values for each
counter), with filtering, and query type parameters. The graph attribute retrieves time based counter values
of counters.
Sample Request
GET /esa/api/v2.0/reporting/mail_incoming_ip_hostname_detail?startDate=
2017-09-10T19:00:00.000Z&endDate=2018-09-24T23:00:00.000Z&device_type=esa&filterBy
=ip_address&filterOperator=begins_with&filterValue=10&query_type=graph
HTTP/1.1
cache-control: no-cache
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
Connection: keep-alive

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Sat, 17 Nov 2018 18:49:42 GMT
Content-type: application/json
Content-Length: 74110
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"meta": {
"totalCount": -1
},
"data": {
"type": "mail_incoming_ip_hostname_detail",
"resultSet": {
"dns_verified": {
"10.76.68.103": [
{"2017-09-01T00:00:00.000Z to 2017-09-30T23:59:00.000Z": 2},
{"2017-10-01T00:00:00.000Z to 2017-10-31T23:59:00.000Z": 1},
...

...
{"2018-09-01T00:00:00.000Z to 2018-09-30T23:59:00.000Z": 1}
],
"10.76.71.211": [
{"2017-09-01T00:00:00.000Z to 2017-09-30T23:59:00.000Z": 1},
{"2017-10-01T00:00:00.000Z to 2017-10-31T23:59:00.000Z": 3},
...

...
{"2017-11-01T00:00:00.000Z to 2017-11-30T23:59:00.000Z": 1},
{"2017-12-01T00:00:00.000Z to 2017-12-31T23:59:00.000Z": 0}

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
16
APIs for Email
Retrieving Multiple Values for Multiple Counters, with Multiple Values for Each Counter

],

},
{
"2018-09-01T00:00:00.000Z to 2018-09-30T23:59:00.000Z": 0
}
]
},
"last_sender_group": {
"10.76.68.103": [
{"2017-09-01T00:00:00.000Z to 2017-09-30T23:59:00.000Z": 4},
{"2018-08-01T00:00:00.000Z to 2018-08-31T23:59:00.000Z": 0},
}
],
"10.76.71.211": [
{"2017-09-01T00:00:00.000Z to 2017-09-30T23:59:00.000Z": 2},
{"2017-10-01T00:00:00.000Z to 2017-10-31T23:59:00.000Z": 2},

}
]
},
"total_threat_recipients": {
"10.76.68.103": [
{"2017-09-01T00:00:00.000Z to 2017-09-30T23:59:00.000Z": 2},
{"2017-10-01T00:00:00.000Z to 2017-10-31T23:59:00.000Z": 20},
...

...
{"2018-08-01T00:00:00.000Z to 2018-08-31T23:59:00.000Z": 0},

}
]
},
"threat_content_filter": {
"10.76.68.103": [
{"2017-09-01T00:00:00.000Z to 2017-09-30T23:59:00.000Z": 0},
{"2017-10-01T00:00:00.000Z to 2017-10-31T23:59:00.000Z": 1},
...

...
}
]
},
"total_graymail_recipients": {
"10.76.68.103": [
{"2017-09-01T00:00:00.000Z to 2017-09-30T23:59:00.000Z": 0},
{"2017-10-01T00:00:00.000Z to 2017-10-31T23:59:00.000Z": 4},
...

...

{"2018-08-01T00:00:00.000Z to 2018-08-31T23:59:00.000Z": 0},

{"2018-09-01T00:00:00.000Z to 2018-09-30T23:59:00.000Z": 0}
]
},
"total_clean_recipients": {
"10.76.68.103": [
{"2018-08-01T00:00:00.000Z to 2018-08-31T23:59:00.000Z": 5},
{"2018-09-01T00:00:00.000Z to 2018-09-30T23:59:00.000Z": 0}
]
},
"sbrs_score": {
"10.76.68.103": [
{"2017-09-01T00:00:00.000Z to 2017-09-30T23:59:00.000Z": 3},

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
17
 APIs for Email
Tracking APIs

...

...
{"2018-08-01T00:00:00.000Z to 2018-08-31T23:59:00.000Z": 0},
{"2018-09-01T00:00:00.000Z to 2018-09-30T23:59:00.000Z": 0}
]
},
"blocked_reputation": {
"10.76.68.103": [
{"2017-09-01T00:00:00.000Z to 2017-09-30T23:59:00.000Z": 0},
]
}
}
}
}

Tracking APIs
You can search for messages or a group of messages that match criteria that you specify. You can retrieve
messages' details, rejected connections ' details, and see the status of a specific message in the email stream.
The various API categories for tracking are:
• Searching for Messages, on page 18
• Rejected Connections, on page 23
• Message Details, on page 24
• DLP Details, on page 27
• AMP Details, on page 28
• URL Details, on page 30
• Connection Details, on page 32
• Remediation Details, on page 34

Searching for Messages

You can search for messages that match multiple attributes. The syntax and supported attributes are given
below:

Synopsis GET/esa/api/v2.0/message-tracking/messages?resource_attribute

Supported See AsyncOS 13.5.1 API - Addendum to the Getting Started guide for Email Security
Resource Appliances for more information.
Attributes

Request Host, Accept, Authorization

Headers

Response Content-Type, Content-Length, Connection

Headers

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
18
APIs for Email
Searching for Messages

Example
This example shows a query to retrieve messages, with the time range, message delivery status, appliance
(which processed the emails), offset and limit parameters.
Sample Request
GET /esa/api/v2.0/message-tracking/messages?startDate=2018-01-01T00:00:00.000Z&
endDate=2018-11-20T09:36:00.000Z&ciscoHost=All_Hosts&
searchOption=messages&offset=0&limit=20
HTTP/1.1
cache-control: no-cache
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
Connection: keep-alive

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Tue, 20 Nov 2018 09:29:48 GMT
Content-type: application/json
Content-Length: 6693
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"meta": {
"num_bad_records": 7,
"totalCount": 13
},
"data": [
{
"attributes": {
"direction": "incoming",
"icid": 110,
"senderGroup": "UNKNOWNLIST",
"sender": "confikr.qa",
"replyTo": "N/A",
"timestamp": "15 Oct 2018 08:33:19 (GMT)",
"hostName": "esa01",
"subject": "message is good",
"mid": [
110
],
"isCompleteData": true,
"messageStatus": "Delivered",
"mailPolicy": [
"DEFAULT"
],
"senderIp": "10.8.91.18",
"verdictChart": "0",
"senderDomain": "N/A",
"recipient": [
"confikr@cisco.com"
],
"sbrs": "None",
"serialNumber": "4229CAEC09527FD2570C-F028BAE54A11"

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
19
 APIs for Email
Searching for Messages

}
},
{
"attributes": {
"direction": "incoming",
"icid": 103,
"senderGroup": "UNKNOWNLIST",
"sender": "confikr@example.com",
"replyTo": "N/A",
"timestamp": "15 Oct 2018 08:24:39 (GMT)",
"hostName": "esa01",
"subject": "message is good",
"mid": [
104
],
"isCompleteData": true,
"messageStatus": "Delivered",
"mailPolicy": [
"DEFAULT"
],
"senderIp": "10.8.91.18",
"verdictChart": "0",
"senderDomain": "example.com",
"recipient": [
"4201@ironport.com"
],
"sbrs": "None",
"serialNumber": "4229CAEC09527FD2570C-F028BAE54A11"
}
},
{
"attributes": {
"direction": "incoming",
"icid": 105,
"senderGroup": "UNKNOWNLIST",
"sender": "confikr@example.com",
"replyTo": "N/A",
"timestamp": "15 Oct 2018 08:24:39 (GMT)",
"hostName": "esa01",
"subject": "message is good",
"mid": [
103
],
"isCompleteData": true,
"messageStatus": "Delivered",
"mailPolicy": [
"DEFAULT"
],
"senderIp": "10.8.91.18",
"verdictChart": "0",
"senderDomain": "example.com",
"recipient": [
"4417@ironport.com"
],
"sbrs": "None",
"serialNumber": "4229CAEC09527FD2570C-F028BAE54A11"
}
},
{
"attributes": {
"direction": "incoming",
"icid": 107,
"senderGroup": "UNKNOWNLIST",
"sender": "confikr@example.com",

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
20
APIs for Email
Searching for Messages

"replyTo": "N/A",
"timestamp": "15 Oct 2018 08:24:39 (GMT)",
"hostName": "esa01",
"subject": "message is good",
"mid": [
102
],
"isCompleteData": true,
"messageStatus": "Delivered",
"mailPolicy": [
"DEFAULT"
],
"senderIp": "10.8.91.18",
"verdictChart": "0",
"senderDomain": "example.com",
"recipient": [
"3396@ironport.com"
],
"sbrs": "None",
"serialNumber": "4229CAEC09527FD2570C-F028BAE54A11"
}
},
{
"attributes": {
"direction": "incoming",
"icid": 106,
"senderGroup": "UNKNOWNLIST",
"sender": "confikr@example.com",
"replyTo": "N/A",
"timestamp": "15 Oct 2018 08:24:39 (GMT)",
"hostName": "esa01",
"subject": "message is good",
"mid": [
101
],
"isCompleteData": true,
"messageStatus": "Delivered",
"mailPolicy": [
"DEFAULT"
],
"senderIp": "10.8.91.18",
"verdictChart": "0",
"senderDomain": "example.com",
"recipient": [
"9985@ironport.com"
],
"sbrs": "None",
"serialNumber": "4229CAEC09527FD2570C-F028BAE54A11"
}
},
{
"attributes": {
"direction": "incoming",
"icid": 100,
"senderGroup": "UNKNOWNLIST",
"sender": "confikr@example.com",
"replyTo": "N/A",
"timestamp": "15 Oct 2018 08:24:39 (GMT)",
"hostName": "esa01",
"subject": "message is good",
"mid": [
100
],
"isCompleteData": true,

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
21
 APIs for Email
Searching for Messages

"messageStatus": "Delivered",
"mailPolicy": [
"DEFAULT"
],
"senderIp": "10.8.91.18",
"verdictChart": "0",
"senderDomain": "example.com",
"recipient": [
"1023@ironport.com"
],
"sbrs": "None",
"serialNumber": "4229CAEC09527FD2570C-F028BAE54A11"
}
},
{
"attributes": {
"direction": "incoming",
"icid": 104,
"senderGroup": "UNKNOWNLIST",
"sender": "confikr@example.com",
"replyTo": "N/A",
"timestamp": "15 Oct 2018 08:24:39 (GMT)",
"hostName": "esa01",
"subject": "message is good",
"mid": [
99
],
"isCompleteData": true,
"messageStatus": "Delivered",
"mailPolicy": [
"DEFAULT"
],
"senderIp": "10.8.91.18",
"verdictChart": "0",
"senderDomain": "example.com",
"recipient": [
"182@ironport.com"
],
"sbrs": "None",
"serialNumber": "4229CAEC09527FD2570C-F028BAE54A11"
}
},
{
"attributes": {
"direction": "incoming",
"icid": 98,
"senderGroup": "UNKNOWNLIST",
"sender": "confikr@example.com",
"replyTo": "N/A",
"timestamp": "15 Oct 2018 08:24:39 (GMT)",
"hostName": "esa01",
"subject": "message is good",
"mid": [
98
],
"isCompleteData": true,
"messageStatus": "Delivered",
"mailPolicy": [
"DEFAULT"
],
"senderIp": "10.8.91.18",
"verdictChart": "0",
"senderDomain": "example.com",
"recipient": [

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
22
 APIs for Email
Rejected Connections

"8668@ironport.com"
],
"sbrs": "None",
"serialNumber": "4229CAEC09527FD2570C-F028BAE54A11"
}
}
]
}

Rejected Connections
You can retrieve details of rejected connections with different attributes as explained below.

Synopsis GET /api/v2.0/message-tracking/messages?resource_attribute

Supported Duration This is a required parameter. All API queries should be accompanied with this
Resource parameter.
Attributes startdate=YYYY-MM-DDThh:mm:00.000Z&endDate=YYYY-MM-DDThh:mm:00.000Z

Aggregate report(s) for the specified duration.

Search • searchOption=<value>
Option
This attribute has a single permitted value when querying for rejected
connections. For example:
searchOption=rejected_connections

Sender IP • senderIp=<value>
This is a user defined value. Use the IP address of the server which sends
messages. For example:
senderIp=10.76.70.112

Lazy You should use both these parameters. If you use either, you will not receive
Loading data in the response.
• offset=<value>
Specify an offset value to retrieve a subset of records starting with the
offset value. Offset works with limit, which determines how many records
to retrieve starting from the offset.
• limit=<value>
Specify the number of records to retrieve.

Request Host, Accept, Authorization

Headers

Response Content-Type, Content-Length, Connection

Headers

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
23
 APIs for Email
Message Details

Example
This example shows a query to retrieve details of rejected connections, with the duration, sender IP address,
search option, offset and limit attributes.
Sample Request
GET /esa/api/v2.0/message-tracking/messages?startDate=2016-11-16T00:00:00.000Z&endDate=
2018-11-16T14:22:00.000Z&senderIp=10.76.70.112&searchOption=rejected_connections&offset=0&limit=20
HTTP/1.1
cache-control: no-cache
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
Connection: keep-alive

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Tue, 20 Nov 2018 11:26:22 GMT
Content-type: application/json
Content-Length: 436
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"meta": {
"num_bad_records": 3,
"totalCount": 1
},
"data": [
{
"attributes": {
"icid": 40,
"timestamp": "10 Jul 2018 03:19:56 (GMT)",
"hostName": "Name unresolved",
"rejected": "(ICID 40) SMTP authentication failed for user fail
using AUTH mechanism PLAIN with profile failAuthFailoverExists.",
"messageStatus": "REJECTED",
"senderIp": "10.76.70.112",
"senderGroup": "UNKNOWNLIST",
"sbrs": "None",
"serialNumber": "848F69E85EEF-6R50TW1"
}
}
]
}

Message Details
You can retrieve details of messages with different attributes as explained below.

Synopsis GET /api/v2.0/message-tracking/details?resource_attribute

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
24
APIs for Email
Message Details

Supported See AsyncOS 13.5.1 API - Addendum to the Getting Started guide for Email Security
Resource Appliances for more information.
Attributes

Request Host, Accept, Authorization

Headers

Response Content-Type, Content-Length, Connection

Headers

Example
This example shows a query to retrieve details of a specific message identified by it's icid, mid and the
appliance' serial number.
Sample Request
GET /esa/api/v2.0/message-tracking/details?endDate=2018-11-16T12:09:00.000Z&icid
=19214&mid=22125&serialNumber=64122536256E-FCH1812V1ST&startDate=2018-11-16T00:00:00.000Z
HTTP/1.1
cache-control: no-cache
Authorization: Basic YWRtaW46Q2lzY28xMjMk
User-Agent: curl/7.54.0
Accept: */*
Host: m680q09.ibqa.sgg.cisco.com:6080
accept-encoding: gzip, deflate
Connection: keep-alive

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Mon, 19 Nov 2018 10:28:53 GMT
Content-type: application/json
Content-Length: 5271
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"data": {
"messages": {
"direction": "outgoing",
"smtpAuthId": "",
"sender": "cf_drop_in@vm30bsd0004.ibqa",
"midHeader": "<20181116111948.15660.34357@vm30bsd0199.ibqa>",
"timestamp": "16 Nov 2018 11:19:48 (GMT)",
"showAMP": true,
"hostName": "c680q07.ibqa (10.76.71.196)",
"mid": [
22125
],
"sendingHostSummary": {
"reverseDnsHostname": "vm30bsd0199.ibqa (verified)",
"ipAddress": "10.76.70.111",
"sbrsScore": "not enabled"
},
"summary": [
{

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
25
 APIs for Email
Message Details

"timestamp": "16 Nov 2018 11:19:48 (GMT)",

"description": "ICID 19214 sender_group: RELAYLIST sender_ip:
10.76.70.111, sbrs: not enabled",
"lastEvent": false
},
{
"timestamp": "16 Nov 2018 11:19:48 (GMT)",
"description": "Protocol SMTP interface Management (IP 10.76.71.196)
on incoming connection
(ICID 19214) from sender IP 10.76.70.111. Reverse DNS host
vm30bsd0199.ibqa verified yes.",
"lastEvent": false
},
...

...
{
"timestamp": "16 Nov 2018 11:20:12 (GMT)",
"description": "Message 22125 scanned by Advanced Malware Protection
engine. Final verdict
: UNKNOWN","lastEvent": false
},
{
"timestamp": "16 Nov 2018 11:20:12 (GMT)",
"description": "Message 22125 contains attachment
'driver_license_germany.txt' (SHA256 7e3dee4dac
8f4af561d1108c4b237e5e139bd8d3ddc8518455d3b5fb7e7a70c3).",
"lastEvent": false
},
{
"timestamp": "16 Nov 2018 11:20:12 (GMT)",
"description": "Message 22125 attachment 'driver_license_germany.txt'
scanned by Advanced Malware
Protection engine. File Disposition: Unknown",
"lastEvent": false
},
{
"timestamp": "16 Nov 2018 11:20:12 (GMT)",
"description": "Message 22125 Delivery Status: DROPPED",
"lastEvent": false
},
{
"timestamp": "16 Nov 2018 11:20:12 (GMT)",
"description": "Message 22125 Verdict chart: 01131212",
"lastEvent": true
}
],
"attachments": [
"driver_license_germany.txt"
],
"messageSize": "765 (Bytes)",
"isCompleteData": true,
"showDLP": true,
"messageStatus": "Dropped by DLP",
"showURL": false,
"mailPolicy": [
"DEFAULT"
],
"senderGroup": "RELAYLIST",
"recipient": [
"7799@vm30bsd0004.ibqa"
],
"showSummaryTimeBox": true,
"subject": "Testing"

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
26
 APIs for Email
DLP Details

}
}
}

DLP Details
You can retrieve details of DLP of messages with different attributes as explained below.

Synopsis GET /api/v2.0/message-tracking/dlp-details?resource_attribute

Supported Duration This is a required parameter. All API queries should be accompanied with this
Resource parameter.
Attributes startdate=YYYY-MM-DDThh:mm:00.000Z&endDate=YYYY-MM-DDThh:mm:00.000Z

Aggregate report(s) for the specified duration.

Serial • serialNumber=<value>
Number
Specify the serial number of the appliance.

Message ID You should use both these parameters. If you use either, you will not receive
and data in the response.
Injection
• icid=<value>
Connection
ID Specify the icid of the message.
• mid=<value>
Specify the mid of the message.

Request Host, Accept, Authorization

Headers

Response Content-Type, Content-Length, Connection

Headers

Example
This example shows a query to retrieve the DLP details of a specific message identified by it's icid, mid and
serial number.
Sample Request
GET /esa/api/v2.0/message-tracking/dlp-details?endDate=2018-11-16T11:25:00.000Z&icid=19213
&mid=22124&serialNumber=64122536256E-FCH1812V1ST&startDate=2018-11-09T00:00:00.000Z
HTTP/1.1
cache-control: no-cache
Postman-Token: ab16ff7f-847e-4221-a2a2-01de50a33fea
Authorization: Basic YWRtaW46Q2lzY28xMjMk
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
Connection: keep-alive

Sample Response

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
27
 APIs for Email
AMP Details

HTTP/1.1 200 OK
Server: API/2.0
Date: Mon, 19 Nov 2018 10:38:44 GMT
Content-type: application/json
Content-Length: 820
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"data": {
"messages": {
"direction": "outgoing",
"smtpAuthId": "",
"sender": "cf_drop_in@vm30bsd0004.ibqa",
"midHeader": "<20181116110108.15629.41969@vm30bsd0199.ibqa>",
"timestamp": "16 Nov 2018 11:01:08 (GMT)",
"hostName": "c680q07.ibqa (10.76.71.196)",
"mid": [
22124
],
"sendingHostSummary": {},
"attachments": [
"driver_license_germany.txt"
],
"messageSize": "765 (Bytes)",
"dlpDetails": {
"violationSeverity": "HIGH",
"dlpMatchedContent": [
{
"messagePartMatch": [
{
"classifier": "Driver License Numbers (Germany)",
"classifierMatch": [
"driver license number: B072RRE2I51"
]
}
],
"messagePart": "driver_license_germany.txt"
}
],
"mid": "22124",
"riskFactor": 16,
"dlpPolicy": "Driver License Numbers (Germany)"
},
"showDLPDetails": true,
"senderGroup": "RELAYLIST",
"recipient": [
"6406@vm30bsd0004.ibqa"
],
"subject": "Testing"
}
}
}

AMP Details
You can retrieve Advanced Malware Protection action details of messages with different attributes as explained
below.

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
28
APIs for Email
AMP Details

Synopsis GET /api/v2.0/message-tracking/amp-details?resource_attribute

Supported Duration This is a required parameter. All API queries should be accompanied with this
Resource parameter.
Attributes startdate=YYYY-MM-DDThh:mm:00.000Z&endDate=YYYY-MM-DDThh:mm:00.000Z

Aggregate report(s) for the specified duration.

Serial • serialNumber=<value>
Number
Specify the serial number of the appliance.

Message ID You should use both these parameters. If you use either, you will not receive
and data in the response.
Injection
• icid=<value>
Connection
ID Specify the icid of the message.
• mid=<value>
Specify the mid of the message.

Request Host, Accept, Authorization

Headers

Response Content-Type, Content-Length, Connection

Headers

Example
This example shows a query to retrieve the Advanced Malware Protection action details of a specific message
identified by it's icid, mid and serial number.
Sample Request
GET /esa/api/v2.0/message-tracking/amp-details?endDate=2018-11-16T11:25:00.000Z&icid=19213
&mid=22124&serialNumber=64122536256E-FCH1812V1ST&startDate=2018-11-09T00:00:00.000Z
HTTP/1.1
cache-control: no-cache
Authorization: Basic YWRtaW46Q2lzY28xMjMk
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
Connection: keep-alive

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Mon, 19 Nov 2018 10:51:08 GMT
Content-type: application/json
Content-Length: 1088
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
29
 APIs for Email
URL Details

{
"data": {
"messages": {
"showAMPDetails": true,
"direction": "outgoing",
"smtpAuthId": "",
"sender": "cf_drop_in@vm30bsd0004.ibqa",
"midHeader": "<20181116110108.15629.41969@vm30bsd0199.ibqa>",
"timestamp": "16 Nov 2018 11:01:08 (GMT)",
"hostName": "c680q07.ibqa (10.76.71.196)",
"mid": [
22124
],
"sendingHostSummary": {},
"attachments": [
"driver_license_germany.txt"
],
"messageSize": "765 (Bytes)",
"ampDetails": [
{
"timestamp": "16 Nov 2018 11:01:08 (GMT)",
"description": "File reputation query initiating. File Name =
driver_license_germany.txt
, MID = 22124, File Size = 42 bytes, File Type = text/plain"
},
{
"timestamp": "16 Nov 2018 11:01:09 (GMT)",
"description": "Response received for file reputation query from Cloud.
File Name = driver
_license_germany.txt, MID = 22124, Disposition = FILE UNKNOWN, Malware
= None, Analysis
Score = 0, sha256 =
7e3dee4dac8f4af561d1108c4b237e5e139bd8d3ddc8518455d3b5fb7e7a70c3,
upload_action = Recommended to send the file for analysis",
"lastEvent": true
}
],
"senderGroup": "RELAYLIST",
"recipient": [
"6406@vm30bsd0004.ibqa"
],
"subject": "Testing"
}
}
}

URL Details
You can retrieve the URL details of messages with different attributes as explained below.

Synopsis GET /api/v2.0/message-tracking/url-details?resource_attribute

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
30
APIs for Email
URL Details

Supported Duration This is a required parameter. All API queries should be accompanied with this
Resource parameter.
Attributes startdate=YYYY-MM-DDThh:mm:00.000Z&endDate=YYYY-MM-DDThh:mm:00.000Z

Aggregate report(s) for the specified duration.

Serial • serialNumber=<value>
Number
Specify the serial number of the appliance.

Message ID You should use both these parameters. If you use either, you will not receive
and data in the response.
Injection
• icid=<value>
Connection
ID Specify the icid of the message.
• mid=<value>
Specify the mid of the message.

Request Host, Accept, Authorization

Headers

Response Content-Type, Content-Length, Connection

Headers

Example
This example shows a query to retrieve the URL details of a specific message identified by it's icid, mid and
serial number.
Sample Request
GET /esa/api/v2.0/message-tracking/url-details?endDate=2018-11-16T11:25:00.000Z&icid=19124&mid
=21981&serialNumber=64122536256E-FCH1812V1ST&startDate=2018-11-09T00:00:00.000Z
HTTP/1.1
cache-control: no-cache
Authorization: Basic YWRtaW46Q2lzY28xMjMk
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
Connection: keep-alive

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Mon, 19 Nov 2018 10:58:21 GMT
Content-type: application/json
Content-Length: 3697
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
31
 APIs for Email
Connection Details

"data": {
"messages": {
"direction": "incoming",
"smtpAuthId": "",
"sdrAge": "31 years 11 months 18 days",
"sender": "cf_quar_in@vm30bsd0004.ibqa",
"midHeader": "",
"urlDetails": [
{
"timestamp": "15 Nov 2018 10:29:04 (GMT)",
"description": "Message 21981 URL: https://www.google.com/, URL category:
Search
Engines and Portals, Condition: URL Category Rule."
},
...
...
{
"timestamp": "15 Nov 2018 10:29:04 (GMT)",
"description": "Message 21983 rewritten URL
u'http://stage.secure-web.sco.cisco.com/
1ytss9mMSYP-JYs4LQ0sT6QALREFaFw/http%3A%2F%2Fdrugstorehost.ru'."
},
{
"timestamp": "15 Nov 2018 10:29:04 (GMT)",
"description": "Message 21983 rewritten URL
u'https://stage.secure-web.sco.cisco.com/

1ymzrg34NKpT-_17H5_rS9dukFQ0FXsvLnYCHc4Eg/https%3A%2F%2Fwww.google.com%2F'."
}
],
"sdrCategory": "N/A",
"hostName": "c680q07.ibqa (10.76.71.196)",
"mid": [
21981,
21982,
21983,
21984
],
"sendingHostSummary": {},
"attachments": [],
"sdrReputation": "neutral",
"showURLDetails": true,
"senderGroup": "UNKNOWNLIST",
"recipient": [
"4969@vm30bsd0004.ibqa"
],
"subject": "[SUSPICIOUS MESSAGE] [SUSPECTED SPAM] Testing VOF"
}
}
}

Connection Details
You can retrieve connection details of messages with different attributes as explained below.

Synopsis GET /api/v2.0/message-tracking/connection-details?resource_attribute

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
32
APIs for Email
Connection Details

Supported Duration This is a required parameter. All API queries should be accompanied with this
Resource parameter.
Attributes startdate=YYYY-MM-DDThh:mm:00.000Z&endDate=YYYY-MM-DDThh:mm:00.000Z

Aggregate report(s) for the specified duration.

Serial • serialNumber=<value>
Number
Specify the serial number of the appliance.

Message ID You should use both these parameters. If you use either, you will not receive
and data in the response.
Injection
• icid=<value>
Connection
ID Specify the icid of the message.
• mid=<value>
Specify the mid of the message.

Request Host, Accept, Authorization

Headers

Response Content-Type, Content-Length, Connection

Headers

Example
This example shows a query to retrieve the connection details of a specific message identified by it's icid, mid
and serial number.
Sample Request
GET /esa/api/v2.0/message-tracking/connection-details?endDate=2018-11-16T11:25:00.
000Z&icid=19213&mid=22124&serialNumber=64122536256E-FCH1812V1ST&startDate=2018-11-09T00:00:00.000Z
HTTP/1.1
cache-control: no-cache
Authorization: Basic YWRtaW46Q2lzY28xMjMk
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
Connection: keep-alive

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Mon, 19 Nov 2018 11:08:56 GMT
Content-type: application/json
Content-Length: 669
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
33
 APIs for Email
Remediation Details

"senderGroup": "RELAYLIST",
"messages": {
"summary": [
{"timestamp": "16 Nov 2018 11:01:08 (GMT)",
"description": "ICID 19213 sender_group: RELAYLIST sender_ip: 10.76.70.111,

sbrs: not enabled",

"lastEvent": false},
{"timestamp": "16 Nov 2018 11:01:08 (GMT)",
"description": "Protocol SMTP interface Management (IP 10.76.71.196) on
incoming connection (ICID 19213) from sender IP 10.76.70.111. Reverse DNS
host vm30bsd0199.com verified yes.",
"lastEvent": false},
{"timestamp": "16 Nov 2018 11:01:08 (GMT)",
"description": "(ICID 19213) RELAY sender group RELAYLIST match 10.0.0.0/8

SBRS not enabled country 10.76.70.111",

"lastEvent": true}
]
},
"sbrs": "not enabled"
}

Remediation Details
You can retrieve the remediation details of the messages remediated using Mailbox Search and Remediate.

Synopsis GET /api/v2.0/message-tracking/remediation-details?resource_attribute

Supported See AsyncOS 13.5.1 API - Addendum to the Getting Started guide for Email Security
Resource Appliances for more information.
Attributes

Request Host, Accept, Authorization

Headers

Response Content-Type, Content-Length, Connection

Headers
This example shows a query to retrieve the remediation details of the message such as
remediation status, batch details, etc.

Sample Request
GET esa/api/v2.0/message-tracking/remediation-details?batchID=admin_1590646987
&endDate=2020-05-28T14:24:00.000Z&searchOption=batch_details&startDate=2020-05-26T00:00:00.000Z
HTTP/1.1
cache-control: no-cache
Authorization: Basic YWRtaW46Q2lzY28xMjMk
User-Agent: curl/7.54.0
Accept: */*
Host: m680q09.ibqa.sgg.cisco.com:6080
accept-encoding: gzip, deflate, br
Connection: keep-alive

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Mon, 25 May 2020 10:28:53 GMT
Content-type: application/json
Content-Length: 5271

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
34
 APIs for Email
Quarantine

Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email, portal, cache-control,
pragma
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken
{
"batch_details": {
"b_init_username": "admin",
"mor_action": "Delete",
"b_init_time": 1590646987,
"batch_name": "Re7",
"batch_desc": "N/A",
"b_init_source": "ESA 117"
},
"message_details": [
{
"delivered_at": 1584574165,
"mid": "3",
"from_email": "kr@mar-esa.com",
"recipient_email": "krs@onpremesa2019.com",
"mor_status": "Success",
"msg_read": "0"
},
{
"delivered_at": 1584574165,
"mid": "3",
"from_email": "kr@mar-esa.com",
"recipient_email": "krc@mar-esa.com",
"mor_status": "Success",
"msg_read": "0"
},
{
"delivered_at": 1584574165,
"mid": "3",
"from_email": "kr@mar-esa.com",
"recipient_email": "anonpremnew@mar-esa.com",
"mor_status": "Success",
"msg_read": "0"
},
{
"delivered_at": 1584574165,
"mid": "3",
"from_email": "kr@mar-esa.com",
"recipient_email": "user5@scale.com",
"mor_status": "Failed",
"msg_read": "N/A"
}
]
}
}
}

Quarantine
Using API queries for quarantine, you can retrieve all information about messages in quarantine. You can
action on the messages by releasing, deleting, and delaying their exit. APIs for quarantine are broadly classified
under:
• APIs for Spam Quarantine, on page 36

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
35
 APIs for Email
APIs for Spam Quarantine

• APIs for Other Quarantine, on page 63

APIs for Spam Quarantine

You can query for messages in the spam quarantine that match multiple attributes, delete or release messages.
• Searching for Messages, on page 36
• Retrieving Message Details, on page 39
• Releasing Messages, on page 42
• Deleting Messages, on page 41
• Searching for Safelist and Blocklist Entries, on page 43
• Adding, Editing, and Appending Safelist and Blocklist Entries, on page 46
• Deleting Safelist or Blocklist Entries, on page 59

Searching for Messages

You can search for messages in the spam quarantine that match multiple attributes. The syntax and supported
attributes are given below:

Synopsis GET /api/v2.0/quarantine/messages?resource_attribute

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
36
APIs for Email
Searching for Messages

Supported Duration This is a required parameter. Use this parameter with all API queries.
Resource
• startdate=YYYY-MM-DDThh:mm:00.000Z&endDate=YYYY-MM-DDThh:mm:00.000Z
Attributes
Messages quarantined during this time range.

Quarantine • quarantineType=<value>
Type
The accepted value is spam.
quarantineType=spam

Sorting You can specify the value and the direction order the results.
• orderBy=<value>
Valid values are:
• from_address
• to_address
• subject

• orderDir=<value>
Valid values are:
• asc
• desc

Lazy You should use both these parameters. If you use either, you will not receive
Loading data in the response.
• offset=<value>
Specify an offset value to retrieve a subset of records starting with the
offset value. Offset works with limit, which determines how many records
to retrieve starting from the offset.
• limit=<value>
Specify the number of records to retrieve.

Envelope
Recipient

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
37
 APIs for Email
Searching for Messages

• envelopeRecipientFilterOperator=<value>
The valid values are:
• contains
• is
• begins_with
• ends_with
• does_not_contain

• envelopeRecipientFilterValue=<value>
The value to search for. This is a user defined value. For example,
envelopeRecipientFilterValue=user

Filtering Filter parameters restrict the data to be included the response.

• filterOperator=<value>
The value to search for. Valid values are:
• contains
• is
• begins_with
• ends_with
• does_not_contain

• filterValue=<value>
The value to search for. This is a user defined value. For example,
filterValue=abc.com

Request Host, Accept, Authorization

Headers

Response Content-Type, Content-Length, Connection

Headers

Example
This example shows a query to retrieve quarantine messages, with the time range, ordering, quarantine type,
offset and limit parameters.
Sample Request
GET /esa/api/v2.0/quarantine/messages?endDate=2018-11-21T23:59:00.000Z&
limit=25&offset=0&orderBy=date&orderDir=desc&quarantineType=spam&startDate=2018-07-01T00:00:00.000Z
HTTP/1.1
cache-control: no-cache
Authorization: Basic YWRtaW46Q2lzY28xMjMk
User-Agent: curl/7.54.0

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
38
 APIs for Email
Retrieving Message Details

Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
Connection: keep-alive

Sample Response

HTTP/1.1 200 OK
Server: API/2.0
Date: Wed, 21 Nov 2018 13:19:37 GMT
Content-type: application/json
Content-Length: 39
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"meta": {
"totalCount": 1
},
"data": [
{
"attributes": {
"envelopeRecipient": [
"test@test.com"
],
"toAddress": [
"danielyeung@mail.qa"
],
"subject": "[SPAM] Spam",
"date": "21 Nov 2018 14:31 (GMT)",
"fromAddress": [
"danel"
],
"size": "1.60K"
},
"mid": 170
}
]
}

Retrieving Message Details

You can retrieve details of a message that match multiple attributes. The syntax and supported attributes are
given below:

Synopsis GET /api/v2.0/quarantine/messages?resource_attribute

Supported Quarantine • quarantineType=<value>

Resource Type
The accepted value is spam.
Attributes
quarantineType=spam

Message ID You must specify the mid of the message to retrieve its details.
• mid=<value>

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
39
 APIs for Email
Retrieving Message Details

Request Host, Accept, Authorization

Headers

Response Content-Type, Content-Length, Connection

Headers

Example
This example shows a query to retrieve details of a specific message.
Sample Request
GET /esa/api/v2.0/quarantine/messages/details?mid=1755&quarantineType=spam
HTTP/1.1
cache-control: no-cache
Authorization: Basic YWRtaW46Q2lzY28xMjMk
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
Connection: keep-alive

Sample Response

HTTP/1.1 200 OK
Server: API/2.0
Date: Wed, 21 Nov 2018 13:43:30 GMT
Content-type: application/json
Content-Length: 6491
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"data": {
"attributes": {
"envelopeRecipient": [
"av_deliver@vm30bsd0004.ibqa"
],
"toAddress": [
"Surya Allena <sallena@cisco.com>"
],
"attachments": [],
"messageBody": "Received: from c680q07.ibqa ([10.76.71.196])\r\n by esa.cisco.com
with
ESMTP; 16 Nov 2018 13:58:55 +0000<br />\nIronPort-SDR:
DjDeJA8ZkD90oA9x+n3eGd9Qa/nliZ1dL
MyxB7dsrdq8oTnn8YSi5amR2qihbeq2eJwvVjskf1\r\n KE7TdyCXSokg==<br />\nX-IronPort-AV:

E=Sophos;i=\"5.56,240,1539648000\"; \r\n d=\"scan'\";a=\"22180\"<br

/>\nIronPort-SDR:
PPj7KDz4Ur8W2ne2fWP/wSOUBwnY3x1XaBz/ryR/98vI6NPraAsA5q7vzUzyaYFpRCWGgfyJaZ\r\n
4UIJbt91/
WFccoWcqqO86zz6rYcRASCSM=<br />\nIronPort-PHdr:
=?us-ascii?q?9a23=3Az7tnkBDwN1EwuviG0ROD
UyQJP3N1i/DPJgcQr6?=\r\n
=?us-ascii?q?AfoPdwSPT7pMbcNUDSrc9gkEXOFd2Cra4c26yO6+jJYi8p2d65",
"date": "16 Nov 2018 13:58 (GMT)",

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
40
 APIs for Email
Deleting Messages

"fromAddress": [
"testuser <testuser@cisco.com>"
],
"subject": "[SUSPICIOUS MESSAGE] [SUSPECTED SPAM] Testing VOF"
},
"mid": 1755
}
}

Deleting Messages
You can delete messages that match various attribute. The syntax and supported attributes are given below:

Synopsis DELETE /api/v2.0/quarantine/messages?resource_attribute

Supported Message ID You should use this parameter to effect the delete action.
Resource
• "mids":[<value>]
Attributes
Specify the mid of the message.

Quarantine "quarantineType":"value"
Type The valid value is spam.

Request {
"quarantineType":"spam",
Body
"mids":[<mid>]
}

Request Host, Accept, Authorization

Headers

Response Content-Type, Content-Length, Connection

Headers

Example
This example shows a query to delete messages.
Sample Request
DELETE /esa/api/v2.0/quarantine/messages HTTP/1.1
Content-Type: application/json
cache-control: no-cache
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
content-length: 41
Connection: keep-alive

{
"quarantineType":"spam",
"mids":[169]
}

Sample Response
HTTP/1.1 200 OK
Server: API/2.0

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
41
 APIs for Email
Releasing Messages

Date: Thu, 22 Nov 2018 05:48:10 GMT

Content-type: application/json
Content-Length: 47
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"data": {
"action": "delete",
"totalCount": 1
}
}

Releasing Messages
You can release a message that matches the mid attribute. The syntax and supported attributes are given
below:

Synopsis POST /api/v2.0/quarantine/messages?resource_attribute

Supported Message ID You should use this parameter to effect the release action.
Resource
• "mids":[<value>]
Attributes
Specify the mid of the message.

Action "action":"value"

The valid value is release.

Quarantine "quarantineType":"value"
Type The valid value is spam.

Request {
"action":"release:
Body
"quarantineType":"spam",
"mids":[<mid>]
}

Request Host, Accept, Authorization

Headers

Response Content-Type, Content-Length, Connection

Headers

Example
This example shows a query to release a specific message with the mid parameter.
Sample Request
POST /esa/api/v2.0/quarantine/messages HTTP/1.1
Content-Type: application/json
cache-control: no-cache
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
42
 APIs for Email
Searching for Safelist and Blocklist Entries

Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
content-length: 61
Connection: keep-alive

{
"action":"release",
"quarantineType":"spam",
"mids":[184]
}

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Thu, 22 Nov 2018 05:41:10 GMT
Content-type: application/json
Content-Length: 48
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"data": {
"action": "release",
"totalCount": 1
}
}

Searching for Safelist and Blocklist Entries

You can retrieve Safelist and Blocklist entries with API queries. The syntax and supported attributes are given
below:

Synopsis GET /api/v2.0/quarantine/safelist?resource_attribute

GET /api/v2.0/quarantine/blocklist?resource_attribute

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
43
 APIs for Email
Searching for Safelist and Blocklist Entries

Supported Action • action=<value>

Resource
Valid value is view.
Attributes

Quarantine quarantineType=<value>
Type The valid value is spam.

View By viewBy=<value>

The valid values are sender, and recipient.

Order By orderBy=<value>

The valid values aresender, and recipient.

Lazy You should use both these parameters. If you use either, you will not receive
Loading data in the response.
• offset=<value>
Specify an offset value to retrieve a subset of records starting with the
offset value. Offset works with limit, which determines how many records
to retrieve starting from the offset.
• limit=<value>
Specify the number of records to retrieve.

Ordering orderDir=<value>

Valid values are:

• asc
• desc

Search This is only supported for the attribute orderBy=recipient.

search=<value>

This is a user defined value.

Request Host, Accept, Authorization

Headers

Response Content-Type, Content-Length, Connection

Headers

Examples

Viewing Safelist and Blocklist entries by recipient:

This sample request shows an example query to retrieve safelist entries by recipient. Use the same query with
blocklist to retrieve blocklist entries by recipient. An example query is shown below:
GET /esa/api/v2.0/quarantine/blocklist?action=view&limit=25&offset=0&orderBy=
recipient&orderDir=desc&quarantineType=spam&search=abc&viewBy=recipient

Sample Request

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
44
APIs for Email
Searching for Safelist and Blocklist Entries

GET /esa/api/v2.0/quarantine/safelist?action=view&limit=25&offset=0&orderBy=
recipient&orderDir=desc&quarantineType=spam&search=abc&viewBy=recipient
HTTP/1.1
Content-Type: application/json
cache-control: no-cache
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
Connection: keep-alive

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Fri, 23 Nov 2018 09:08:39 GMT
Content-type: application/json
Content-Length: 126
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"meta": {
"totalCount": 1
},
"data": [
{
"senderList": [
"space.com",
"xyz.com",
"abc.com"
],
"recipientAddress": "u1@space.com"
}
]
}

Viewing Safelist and Blocklist entries by sender:

This sample request shows an example query to retrieve blocklist entries by sender. Use the same query with
safelist to retrieve blocklist entries by recipient. An example query is shown below:
GET /esa/api/v2.0/quarantine/safelist?action=view&limit=25&offset=0&orderBy=
sender&orderDir=desc&quarantineType=spam&viewBy=sender

Sample Request
GET /esa/api/v2.0/quarantine/blocklist?action=view&limit=25&offset=0&orderBy=
sender&orderDir=desc&quarantineType=spam&viewBy=sender
HTTP/1.1
Content-Type: application/json
cache-control: no-cache
Postman-Token: 9b9bc6ef-2290-47ce-a84a-077bb805c57f
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: PostmanRuntime/7.4.0
Accept: */*
Host: bgl0090-pod.cisco.com:6080
accept-encoding: gzip, deflate
Connection: keep-alive

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
45
 APIs for Email
Adding, Editing, and Appending Safelist and Blocklist Entries

HTTP/1.1 200 OK
Server: API/2.0
Date: Fri, 23 Nov 2018 09:19:24 GMT
Content-type: application/json
Content-Length: 214
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Fri, 23 Nov 2018 09:08:39 GMT
Content-type: application/json
Content-Length: 126
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"meta": {
"totalCount": 1
},
"data": [
{
"senderList": [
"space.com",
"xyz.com",
"abc.com"
],
"recipientAddress": "u1@space.com"
}
]
}

Adding, Editing, and Appending Safelist and Blocklist Entries

You can add, edit and append Safelist and Blocklist entries. If the record does not exist, the entry is added. If
the record exists, the entry is edited. The syntax and supported attributes are given below:

Synopsis POST /api/v2.0/quarantine/safelist?resource_attribute

POST /api/v2.0/quarantine/blocklist?resource_attribute

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
46
APIs for Email
Adding, Editing, and Appending Safelist and Blocklist Entries

Supported Action • action=<value>

Resource
Valid values are:
Attributes
• add
• edit
• append

Quarantine quarantineType=<value>
Type The valid value is spam.

View By viewBy=<value>

The valid values aresender, and recipient.

Recipient "recipientAddresses": ["value","value",...]

Addresses This is a user defined value. You can enter multiple values.

Recipient "recipientList": ["value","value",...]

List This is a user defined value. You can enter multiple values.

Sender "senderAddresses": ["value","value",...]

Addresses This is a user defined value. You can enter multiple values.

Sender List "senderList": ["value", "value", ...]

This is a user defined value. You can enter multiple values.

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
47
 APIs for Email
Adding, Editing, and Appending Safelist and Blocklist Entries

Request Body Adding a new recipient entry:

{
"action": "add",
"quarantineType": "spam",
"recipientAddresses": ["value","value"],
"senderList": ["value"],
"viewBy": "recipient"
}

Adding a new sender entry:

{
"action": "add",
"quarantineType": "spam",
"senderAddresses": ["value","value"],
"recipientList": ["value"],
"viewBy": "sender"
}

Editing a new recipient entry:

{
"action": "edit",
"quarantineType": "spam",
"recipientAddresses": ["value","value"],
"senderList": ["value"],
"viewBy": "recipient"
}

Editing a new sender entry:

{
"action": "edit",
"quarantineType": "spam",
"senderAddresses": ["value","value"],
"recipientList": ["value"],
"viewBy": "sender"
}

Appending a new recipient entry:

{
"action": "append",
"quarantineType": "spam",
"recipientAddresses": ["value","value"],
"senderList": ["value"],
"viewBy": "recipient"
}

Appending a new sender entry:

{
"action": "append",
"quarantineType": "spam",
"senderAddresses": ["value","value"],
"recipientList": ["value"],
"viewBy": "sender"
}

Request Host, Accept, Authorization

Headers

Response Content-Type, Content-Length, Connection

Headers

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
48
 APIs for Email
Adding Recipient Safelist Entries

Examples
• Adding Recipient Safelist Entries, on page 49
• Adding Sender Safelist Entries, on page 50
• Adding Recipient Blocklist Entries, on page 51
• Adding Sender Blocklist Entries, on page 51
• Editing Recipient Safelist Entries, on page 52
• Editing Sender Safelist Entries, on page 53
• Editing Recipient Blocklist Entries, on page 54
• Editing Sender Blocklist Entries, on page 55
• Appending Recipient Safelist Entries, on page 55
• Appending Sender Safelist Entries, on page 56

Adding Recipient Safelist Entries

This sample request shows a query to add a safelist entry.
Sample Request
POST /esa/api/v2.0/quarantine/safelist
HTTP/1.1
Content-Type: application/json
cache-control: no-cache
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
content-length: 163
Connection: keep-alive

{
"action": "add",
"quarantineType": "spam",
"recipientAddresses": ["user1@acme.com","user2@acme.com"],
"senderList": ["acme.com"],
"viewBy": "recipient"
}

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Fri, 23 Nov 2018 10:22:23 GMT
Content-type: application/json
Content-Length: 115
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"data": {

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
49
 APIs for Email
Adding Sender Safelist Entries

"action": "add",
"recipientAddresses": [
"user1@acme.com",
"user2@acme.com"
],
"senderList": [
"acme.com"
]
}
}

Adding Sender Safelist Entries

This sample request shows a query to add a safelist entry.
Sample Request
POST /esa/api/v2.0/quarantine/safelist HTTP/1.1
Content-Type: application/json
cache-control: no-cache
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
content-length: 155
Connection: keep-alive

{
"action": "add",
"quarantineType": "spam",
"senderAddresses": ["xyz.com","space.com"],
"recipientList": ["user@cronos.com"],
"viewBy": "sender"
}

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Fri, 23 Nov 2018 10:31:28 GMT
Content-type: application/json
Content-Length: 110
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"data": {
"action": "add",
"recipientList": [
"user@cronos.com"
],
"senderAddresses": [
"xyz.com",
"space.com"
]
}
}

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
50
 APIs for Email
Adding Recipient Blocklist Entries

Adding Recipient Blocklist Entries

This sample request shows a query to add a blocklist entry.
Sample Request
POST /esa/api/v2.0/quarantine/blocklist
HTTP/1.1
Content-Type: application/json
cache-control: no-cache
Postman-Token: 55570e07-17fb-436e-9132-9f4998c67e7f
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
content-length: 163
Connection: keep-alive

{
"action": "add",
"quarantineType": "spam",
"recipientAddresses": ["user1@acme.com","user2@acme.com"],
"senderList": ["acme.com"],
"viewBy": "recipient"
}

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Fri, 23 Nov 2018 10:22:23 GMT
Content-type: application/json
Content-Length: 115
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"data": {
"action": "add",
"recipientAddresses": [
"user1@acme.com",
"user2@acme.com"
],
"senderList": [
"acme.com"
]
}
}

Adding Sender Blocklist Entries

This sample request shows a query to add a blocklist entry.
Sample Request
POST /esa/api/v2.0/quarantine/blocklist HTTP/1.1
Content-Type: application/json
cache-control: no-cache
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
51
 APIs for Email
Editing Recipient Safelist Entries

Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
content-length: 155
Connection: keep-alive

{
"action": "add",
"quarantineType": "spam",
"senderAddresses": ["xyz.com","space.com"],
"recipientList": ["user@cronos.com"],
"viewBy": "sender"
}

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Fri, 23 Nov 2018 10:31:28 GMT
Content-type: application/json
Content-Length: 110
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"data": {
"action": "add",
"recipientList": [
"user@cronos.com"
],
"senderAddresses": [
"xyz.com",
"space.com"
]
}
}

Editing Recipient Safelist Entries

This sample request shows a query to add a safelist entry.
Sample Request
POST /esa/api/v2.0/quarantine/safelist
HTTP/1.1
Content-Type: application/json
cache-control: no-cache
Postman-Token: 55570e07-17fb-436e-9132-9f4998c67e7f
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
content-length: 163
Connection: keep-alive

{
"action": "edit",
"quarantineType": "spam",
"recipientAddresses": ["user1@acme.com","user2@acme.com"],
"senderList": ["acme.com"],

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
52
 APIs for Email
Editing Sender Safelist Entries

"viewBy": "recipient"
}

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Fri, 23 Nov 2018 10:22:23 GMT
Content-type: application/json
Content-Length: 115
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"data": {
"action": "edit",
"recipientAddresses": [
"user1@acme.com",
"user2@acme.com"
],
"senderList": [
"acme.com"
]
}
}

Editing Sender Safelist Entries

This sample request shows a query to add a safelist entry.
Sample Request
POST /esa/api/v2.0/quarantine/safelist HTTP/1.1
Content-Type: application/json
cache-control: no-cache
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
content-length: 155
Connection: keep-alive

{
"action": "edit",
"quarantineType": "spam",
"senderAddresses": ["xyz.com","space.com"],
"recipientList": ["user@cronos.com"],
"viewBy": "sender"
}

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Fri, 23 Nov 2018 10:31:28 GMT
Content-type: application/json
Content-Length: 110
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
53
 APIs for Email
Editing Recipient Blocklist Entries

Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"data": {
"action": "edit",
"recipientList": [
"user@cronos.com"
],
"senderAddresses": [
"xyz.com",
"space.com"
]
}
}

Editing Recipient Blocklist Entries

This sample request shows a query to edit a blocklist entry.
Sample Request
POST /esa/api/v2.0/quarantine/blocklist
HTTP/1.1
Content-Type: application/json
cache-control: no-cache
Postman-Token: 55570e07-17fb-436e-9132-9f4998c67e7f
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
content-length: 163
Connection: keep-alive

{
"action": "edit",
"quarantineType": "spam",
"recipientAddresses": ["user1@acme.com","user2@acme.com"],
"senderList": ["acme.com"],
"viewBy": "recipient"
}

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Fri, 23 Nov 2018 10:22:23 GMT
Content-type: application/json
Content-Length: 115
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"data": {
"action": "edit",
"recipientAddresses": [
"user1@acme.com",
"user2@acme.com"
],

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
54
 APIs for Email
Editing Sender Blocklist Entries

"senderList": [
"acme.com"
]
}
}

Editing Sender Blocklist Entries

This sample request shows a query to edit a blocklist entry.
Sample Request
POST /esa/api/v2.0/quarantine/blocklist HTTP/1.1
Content-Type: application/json
cache-control: no-cache
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
content-length: 155
Connection: keep-alive

{
"action": "edit",
"quarantineType": "spam",
"senderAddresses": ["xyz.com","space.com"],
"recipientList": ["user@cronos.com"],
"viewBy": "sender"
}

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Fri, 23 Nov 2018 10:31:28 GMT
Content-type: application/json
Content-Length: 110
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"data": {
"action": "edit",
"recipientList": [
"user@cronos.com"
],
"senderAddresses": [
"xyz.com",
"space.com"
]
}
}

Appending Recipient Safelist Entries

This sample request shows a query to append a safelist entry.
Sample Request

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
55
 APIs for Email
Appending Sender Safelist Entries

POST /esa/api/v2.0/quarantine/safelist
HTTP/1.1
Content-Type: application/json
cache-control: no-cache
Postman-Token: 55570e07-17fb-436e-9132-9f4998c67e7f
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
content-length: 163
Connection: keep-alive

{
"action": "append",
"quarantineType": "spam",
"recipientAddresses": ["user1@acme.com","user2@acme.com"],
"senderList": ["acme.com"],
"viewBy": "recipient"
}

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Fri, 23 Nov 2018 10:22:23 GMT
Content-type: application/json
Content-Length: 115
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"data": {
"action": "append",
"recipientAddresses": [
"user1@acme.com",
"user2@acme.com"
],
"senderList": [
"acme.com"
]
}
}

Appending Sender Safelist Entries

This sample request shows a query to append a safelist entry.
Sample Request
POST /esa/api/v2.0/quarantine/safelist HTTP/1.1
Content-Type: application/json
cache-control: no-cache
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
content-length: 155
Connection: keep-alive

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
56
 APIs for Email
Appending a Recipient Blocklist Entry

{
"action": "append",
"quarantineType": "spam",
"senderAddresses": ["xyz.com","space.com"],
"recipientList": ["user@cronos.com"],
"viewBy": "sender"
}

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Fri, 23 Nov 2018 10:31:28 GMT
Content-type: application/json
Content-Length: 110
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"data": {
"action": "append",
"recipientList": [
"user@cronos.com"
],
"senderAddresses": [
"xyz.com",
"space.com"
]
}
}

Appending a Recipient Blocklist Entry

This sample request shows a query to append blocklist entries.
Sample Request
POST /esa/api/v2.0/quarantine/blocklist
HTTP/1.1
Content-Type: application/json
cache-control: no-cache
Postman-Token: 55570e07-17fb-436e-9132-9f4998c67e7f
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
content-length: 163
Connection: keep-alive

{
"action": "append",
"quarantineType": "spam",
"recipientAddresses": ["user1@acme.com","user2@acme.com"],
"senderList": ["acme.com"],
"viewBy": "recipient"
}

Sample Response

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
57
 APIs for Email
Appending Sender Blocklist Entries

HTTP/1.1 200 OK
Server: API/2.0
Date: Fri, 23 Nov 2018 10:22:23 GMT
Content-type: application/json
Content-Length: 115
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"data": {
"action": "append",
"recipientAddresses": [
"user1@acme.com",
"user2@acme.com"
],
"senderList": [
"acme.com"
]
}
}

Appending Sender Blocklist Entries

This sample request shows a query to append blocklist entries.
Sample Request
POST /esa/api/v2.0/quarantine/blocklist HTTP/1.1
Content-Type: application/json
cache-control: no-cache
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
content-length: 155
Connection: keep-alive

{
"action": "append",
"quarantineType": "spam",
"senderAddresses": ["xyz.com","space.com"],
"recipientList": ["user@cronos.com"],
"viewBy": "sender"
}

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Fri, 23 Nov 2018 10:31:28 GMT
Content-type: application/json
Content-Length: 110
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
58
 APIs for Email
Deleting Safelist or Blocklist Entries

"data": {
"action": "append",
"recipientList": [
"user@cronos.com"
],
"senderAddresses": [
"xyz.com",
"space.com"
]
}
}

Deleting Safelist or Blocklist Entries

You can run API queries to delete safelist or blocklist entries from either the sender or recipient lists.

Synopsis DELETE /api/v2.0/quarantine/safelist?resource_attribute

DELETE /api/v2.0/quarantine/blocklist?resource_attribute

Supported Quarantine quarantineType=<value>

Resource Type The valid value is spam.
Attributes
Recipient "recipientList": ["value","value",...]
List This is a user defined value. You can enter multiple values.

Sender List "senderList": ["value", "value", ...]

This is a user defined value. You can enter multiple values.

View By "viewBy": "value"

Valid values are sender, and recipient

.
Request Body Deleting recipient entries:
{
"quarantineType": "spam",
"recipientList": ["value","value"],
"viewBy": "recipient"
}

Deleting sender entries:

{
"quarantineType": "spam",
"senderList": ["value"],
"viewBy": "sender"
}

Request Host, Accept, Authorization

Headers

Response Content-Type, Content-Length, Connection

Headers

The following APIs are available:

• Deleting Recipient Safelist Entries, on page 60

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
59
 APIs for Email
Deleting Recipient Safelist Entries

• Deleting Sender Safelist Entries, on page 60

• Deleting Recipient Blocklist Entries, on page 61
• Deleting Sender Blocklist Entries, on page 62

Deleting Recipient Safelist Entries

This sample request shows a query to delete a safelist entry.
Sample Request
DELETE /esa/api/v2.0/quarantine/safelist
HTTP/1.1
Content-Type: application/json
cache-control: no-cache
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
content-length: 111
Connection: keep-alive

{
"quarantineType": "spam",
"recipientList": ["user@cronos.com","user3@cosco.com"],
"viewBy": "recipient"
}

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Fri, 23 Nov 2018 12:27:40 GMT
Content-type: application/json
Content-Length: 104
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"data": {
"action": "delete",
"recipientList": [
"user@cronos.com",
"user3@cosco.com"
],
"totalCount": 2
}
}

Deleting Sender Safelist Entries

This sample request shows a query to delete a safelist entry.
Sample Request
DELETE /esa/api/v2.0/quarantine/safelist HTTP/1.1
Content-Type: application/json
cache-control: no-cache

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
60
 APIs for Email
Deleting Recipient Blocklist Entries

Authorization: Basic YWRtaW46aXJvbnBvcnQ=

User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
content-length: 82
Connection: keep-alive

{
"quarantineType": "spam",
"senderList": ["race.com"],
"viewBy": "sender"
}

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Fri, 23 Nov 2018 12:33:41 GMT
Content-type: application/json
Content-Length: 75
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"data": {
"action": "delete",
"totalCount": 1,
"senderList": [
"race.com"
]
}
}

Deleting Recipient Blocklist Entries

This sample request shows a query to delete a blocklist entry.
DELETE /esa/api/v2.0/quarantine/blocklist
HTTP/1.1
Content-Type: application/json
cache-control: no-cache
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
content-length: 111
Connection: keep-alive

{
"quarantineType": "spam",
"recipientList": ["user@cronos.com","user3@cosco.com"],
"viewBy": "recipient"
}

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Fri, 23 Nov 2018 12:27:40 GMT

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
61
 APIs for Email
Deleting Sender Blocklist Entries

Content-type: application/json
Content-Length: 104
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"data": {
"action": "delete",
"recipientList": [
"user@cronos.com",
"user3@cosco.com"
],
"totalCount": 2
}
}

Deleting Sender Blocklist Entries

This sample request shows a query to delete a blocklist entry.
Sample Request
DELETE /esa/api/v2.0/quarantine/blocklist HTTP/1.1
Content-Type: application/json
cache-control: no-cache
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
content-length: 82
Connection: keep-alive

{
"quarantineType": "spam",
"senderList": ["race.com"],
"viewBy": "sender"
}

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Fri, 23 Nov 2018 12:33:41 GMT
Content-type: application/json
Content-Length: 75
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"data": {
"action": "delete",
"totalCount": 1,
"senderList": [
"race.com"
]

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
62
 APIs for Email
APIs for Other Quarantine

}
}

APIs for Other Quarantine

These queries will have the quarantineType resource name as part of the query string.
Quarantine queries support search, sorting, offset, and lazy loading.
• Searching for Messages, on page 63
• Retrieving Message Details, on page 70
• Move Messages, on page 72
• Delaying the Exit of a Message from a Quarantine , on page 73
• Sending a Copy of a Message in Quarantine, on page 75
• Downloading an Attachment, on page 77
• Deleting Messages, on page 78
• Releasing Messages, on page 79
• Viewing the Rule Summary, on page 81
• Searching Based on Rule ID, on page 82
• Releasing Messages from the Rule Summary, on page 85
• Deleting Messages from the Rule Summary, on page 86

Searching for Messages

You can search for messages in the other quarantine that match multiple attributes. The syntax and supported
attributes are given below:

Synopsis GET /api/v2.0/quarantine/messages?resource_attribute

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
63
 APIs for Email
Searching for Messages

Supported Duration This is a required parameter. All API queries should be accompanied with this
Resource parameter.
Attributes
• startdate=YYYY-MM-DDThh:mm:00.000Z&endDate=YYYY-MM-DDThh:mm:00.000Z

Quarantines This parameter specifies the quarantines to search for.

to Search
• quarantines=<value, value, ...>
Valid values are:
Outbreak
Virus
File+Analysis
Unclassified
Policy
<user-defined-quarantine>

Subject • subjectFilterBy=<value>
The valid values are:
contains
starts_with
ends_with
matches_exactly
does_not_contain
does_not_start_with
does_not_end_with
does_not_match

• subjectFilterValue=<value>
This is a user defined value.

Originating originatingEsaIp=<value>
ESA You can specify the IP address of the ESA in which the message was processed.

Attachment
Details

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
64
APIs for Email
Searching for Messages

• attachmentName=<value>
This is a user defined value.
• attachmentSizeFilterBy=<value>
Valid values are:
range
less_than
more_than

• attachmentSizeFromValue=<value_in_KB>
This is a user defined value. Specify an attachment size in KB. This is
applicable when:
• You choose the range attribute for attachmentSizeFilterBy
attachmentSizeFilterBy=range

• You choose the more_than attribute for attachmentSizeFilterBy

attachmentSizeFilterBy=more_than

.
• attachmentSizeToValue=<value_in_KB>
This is a user defined value. Specify an attachment size in KB. This is
applicable when:
• You choose the range attribute for attachmentSizeFilterBy
attachmentSizeFilterBy=range

• You choose the less_than attribute for attachmentSizeFilterBy

attachmentSizeFilterBy=less_than

Quarantine • quarantineType=<value>
Type
The accepted value is pvo.
quarantineType=pvo

Sorting

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
65
 APIs for Email
Searching for Messages

You can specify the value and the direction order the results.
• orderBy=<value>
Values are:
sender
subject
received
scheduledExit
size

• orderDir=<value>
Values are:
asc
desc

Lazy You should use both these parameters. If you use either, you will not receive
Loading data in the response.
• offset=<value>
Specify an offset value to retrieve a subset of records starting with the
offset value. Offset works with limit, which determines how many records
to retrieve starting from the offset.
• limit=<value>
Specify the number of records to retrieve.

Envelope • envelopeRecipientFilterBy=<value>
Recipient
The valid values are:
contains
starts_with
ends_with
matches_exactly
does_not_contain
does_not_start_with
does_not_end_with
does_not_match

• envelopeRecipientFilterValue=<value>
The value to search for. This is a user defined value. For example,
envelopeRecipientFilterValue=user

Envelope
Sender

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
66
APIs for Email
Searching for Messages

• envelopeSenderFilterBy=<value>
The valid values are:
contains
starts_with
ends_with
matches_exactly
does_not_contain
does_not_start_with
does_not_end_with
does_not_match

• envelopeSenderFilterValue=<value>
The value to search for. This is a user defined value. For example,
envelopeRecipientFilterValue=user

Request Host, Accept, Authorization

Headers

Response Content-Type, Content-Length, Connection

Headers

Example
This example shows a query to retrieve messages in the other Policy, Virus and Outbreak quarantines, with
the time range, ordering, quarantine type, offset and limit, originating ESA parameters.
Sample Request
GET
/esa/api/v2.0/quarantine/messages?endDate=2018-11-23T00:00:00.000Z&limit=25&offset=0&orderBy=
received&orderDir=desc&quarantineType=pvo&quarantines=Outbreak,Virus,File+Analysis,Unclassified,Policy&startDate
=2017-11-22T00:00:00.000Z&originatingEsaIp=10.8.91.15
HTTP/1.1
Content-Type: application/json
cache-control: no-cache
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
Connection: keep-alive

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Thu, 22 Nov 2018 09:01:11 GMT
Content-type: application/json
Content-Length: 13093
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
67
 APIs for Email
Searching for Messages

Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS

Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"meta": {
"totalCount": 126
},
"data": [
{
"attributes": {
"received": "21 Nov 2018 10:10 (GMT)",
"sender": "usr2@sender.com",
"subject": "[SUSPICIOUS MESSAGE] Test mail.",
"esaHostName": "esa01",
"inQuarantines": "Policy",
"scheduledExit": "21 Dec 2018 10:10 (GMT)",
"originatingEsaIp": "10.8.91.15",
"quarantineForReason": [
"Content Filter: 'url'"
],
"esaMid": 379,
"recipient": [
"eriferna@mail.qa.sgg.cisco.com"
],
"quarantineForReasonDict": [
{
"reason": [
"Content Filter: 'url'"
],
"quarantineName": "Policy"
}
],
"size": "312.69K"
},
"mid": 166
},
{
"attributes": {
"received": "21 Nov 2018 10:10 (GMT)",
"sender": "usr2@sender.com",
"subject": "[SUSPICIOUS MESSAGE] Test mail.",
"esaHostName": "esa01",
"inQuarantines": "Policy",
"scheduledExit": "21 Dec 2018 10:10 (GMT)",
"originatingEsaIp": "10.8.91.15",
"quarantineForReason": [
"Content Filter: 'url'"
],
"esaMid": 369,
"recipient": [
"eriferna@mail.qa.sgg.cisco.com"
],
"quarantineForReasonDict": [
{
"reason": [
"Content Filter: 'url'"
],
"quarantineName": "Policy"
}
],
"size": "312.69K"
},
"mid": 161
},

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
68
APIs for Email
Searching for Messages

{
"attributes": {
"received": "21 Nov 2018 10:09 (GMT)",
"sender": "usr2@sender.com",
"subject": "[SUSPICIOUS MESSAGE] Test mail.",
"esaHostName": "esa01",
"inQuarantines": "Policy",
"scheduledExit": "21 Dec 2018 10:09 (GMT)",
"originatingEsaIp": "10.8.91.15",
"quarantineForReason": [
"Content Filter: 'url'"
],
"esaMid": 354,
"recipient": [
"eriferna@mail.qa.sgg.cisco.com"
],
"quarantineForReasonDict": [
{
"reason": [
"Content Filter: 'url'"
],
"quarantineName": "Policy"
}
],
"size": "312.69K"
},
"mid": 153
},
{
"attributes": {
"received": "20 Nov 2018 12:42 (GMT)",
"sender": "test@irontest.com",
"subject": "[WARNING: ATTACHMENT UNSCANNED]sadsafasd",
"esaHostName": "esa01",
"inQuarantines": "Policy",
"scheduledExit": "20 Dec 2018 12:42 (GMT)",
"originatingEsaIp": "10.8.91.15",
"quarantineForReason": [
"Message is unscannable by AMP - Service Not Available"
],
"esaMid": 254,
"recipient": [
"test2@irontest.com"
],
"quarantineForReasonDict": [
{
"reason": [
"Message is unscannable by AMP - Service Not Available"
],
"quarantineName": "Policy"
}
],
"size": "330.19K"
},
"mid": 143
},
{
"attributes": {
"received": "20 Nov 2018 12:41 (GMT)",
"sender": "test@irontest.com",
"subject": "[WARNING: ATTACHMENT UNSCANNED]sadsafasd",
"esaHostName": "esa01",
"inQuarantines": "Policy",
"scheduledExit": "20 Dec 2018 12:41 (GMT)",

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
69
 APIs for Email
Retrieving Message Details

"originatingEsaIp": "10.8.91.15",
"quarantineForReason": [
"Message is unscannable by AMP - Service Not Available"
],
"esaMid": 251,
"recipient": [
"test2@irontest.com"
],
"quarantineForReasonDict": [
{
"reason": [
"Message is unscannable by AMP - Service Not Available"
],
"quarantineName": "Policy"
}
],
"size": "330.19K"
},
"mid": 140
}
]
}

Retrieving Message Details

You can retrieve details of a message that match multiple attributes. The syntax and supported attributes are
given below:

Synopsis GET /api/v2.0/quarantine/messages?resource_attribute

Supported Quarantine • quarantineType=<value>

Resource Type
The accepted value is pvo.
Attributes
quarantineType=pvo

Message ID You must specify the mid of the message to retrieve its details.
• mid=<value>

Request Host, Accept, Authorization

Headers

Response Content-Type, Content-Length, Connection

Headers

Example
This example shows a query to retrieve details of a specific message.
Sample Request
GET /esa/api/v2.0/quarantine/messages/details?mid=166&quarantineType=pvo
HTTP/1.1
cache-control: no-cache
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
70
APIs for Email
Retrieving Message Details

accept-encoding: gzip, deflate

Connection: keep-alive

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Thu, 22 Nov 2018 09:16:27 GMT
Content-type: application/json
Content-Length: 1650
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"data": {
"attributes": {
"quarantineDetails": [
{
"received": "21 Nov 2018 10:10 (GMT)",
"esaHostName": "esa01",
"quarantineName": "Policy",
"reason": [
"Content Filter: 'url'"
],
"scheduledExit": "21 Dec 2018 10:10 (GMT)",
"originatingEsaIp": "10.8.91.15"
}
],
"matchedContents": [],
"messagePartDetails": [
{
"attachmentId": 1,
"attachmentSize": "43",
"attachmentName": "[message body]"
},
{
"attachmentId": 2,
"attachmentSize": "307.25K",
"attachmentName": "eicar4.pdf"
}
],
"messageDetails": {
"recipient": [
"eriferna@mail.qa.sgg.cisco.com"
],
"sender": "usr2@sender.com",
"subject": "[SUSPICIOUS MESSAGE] Test mail."
},
"messageBody": "This is a demo mail. http://bit.ly/2zs6KAq<br>\n",
"headers": "IronPort-SDR:
4Sh6scwkvc+t4BgD5601B/l5cTAMkUtJtFAY+/Sk6YwaaSxL2TOzEKHwsn+6KxG+kV2Zg
75sMX<br> DkgdFZYTDPift9VvRsTl0Fz+N6rRgHCB4=<br>X-IPAS-Result:
=?us-ascii?q?A0GSTP/juz9b/+pj4QpOH
oMagXSCU4gely0HhysBAQEBA?=<br>
=?us-ascii?q?QEBeoIOAQEBPQUEAgEFBQEDAwECAgEBLTEkOCyBFxhDiEefIY8MAQ
EBAQYBA?=<br>
=?us-ascii?q?QEBAR2PIQEBhH8FiRODF4FVgUqBJ02RGYVLhA55AYEAgTcBAQE?=<br>
Subject: [SUSPICIOUS MESSAGE] Test mail.<br>Received: from client.cisco.com
(HELO pod1224-client05.ibwsa) ([10.225.99.234])<br>&nbsp; by pod0090-esa01
with ESMTP; 21 Nov 2018 07:01:34 +0000<br>Message-ID: &lt;194652.955603914
-sendEmail@pod1224-client05&gt;<br>From: \"usr2@sender.com\" &lt;usr2@sender

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
71
 APIs for Email
Move Messages

.com&gt;<br>To: \"eriferna@mail.qa.sgg.cisco.com\" &lt;testclient@.cisco.com

&gt;<br>Date: Wed, 21 Nov 2018 10:23:53 +0000<br>X-Mailer: sendEmail-1.55<br
>MIME-Version: 1.0<br>Content-Type: multipart/mixed; boundary=\"----
MIME delimiter for sendEmail-936308.539779024\""
},
"mid": 166
}
}

Move Messages
You can move messages that match multiple attributes. The syntax and supported attributes are given below:

Synopsis POST /api/v2.0/quarantine/messages?resource_attribute

Supported Message ID You should use this parameter to effect the delete action.
Resource
• "mids": [<value>]
Attributes
Specify the mid/s of the message/s.

Quarantine "quarantineName": "<value>"

Type The valid value is pvo.

Destination "destinationQuarantineName": "<value>"

Quarantine The valid values are:
Name
Outbreak
Virus
File+Analysis
Unclassified
Policy
<user-defined-quarantine>

Request {
"action": "move",
Body
"destinationQuarantineName": "<value>",
"mids": [<value>],
"quarantineName": "<value>",
"quarantineType": "pvo"
}

Request Host, Accept, Authorization

Headers

Response Content-Type, Content-Length, Connection

Headers

Example
This example shows a query to move a message.
Sample Request
POST /esa/api/v2.0/quarantine/messages
HTTP/1.1

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
72
 APIs for Email
Delaying the Exit of a Message from a Quarantine

Content-Type: application/json
cache-control: no-cache
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
content-length: 138
Connection: keep-alive
{
"action": "move",
"destinationQuarantineName": "Policy",
"mids": [46],
"quarantineName": "Unclassified",
"quarantineType": "pvo"
}

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Thu, 22 Nov 2018 11:57:40 GMT
Content-type: application/json
Content-Length: 84
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"data": {
"action": "move",
"totalCount": 1,
"destinationQuarantineName": "Policy"
}
}

Delaying the Exit of a Message from a Quarantine

You can delay the exit of messages from a quarantine. The syntax and supported attributes are given below:

Synopsis POST /api/v2.0/quarantine/messages?resource_attribute

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
73
 APIs for Email
Delaying the Exit of a Message from a Quarantine

Supported Message ID • "mids": [value]

Resource
Specify the mid of the message.
Attributes

Quarantine "quarantineType": "value"

Type The valid value is pvo.

Quarantine "quarantineName": "value"

Name The valid values are:
Outbreak
Virus
File+Analysis
Unclassified
Policy
<user-defined-quarantine>

Delay "delay":"value"

The valid values are 8h, 24h, 48h, or 1w.

Request {
"action":"delay",
Body
"delay":"<value>",
"mids": [<value>],
"quarantineName": "<value>",
"quarantineType": "pvo"
}

Request Host, Accept, Authorization

Headers

Response Content-Type, Content-Length, Connection

Headers

Example
This example shows a query to delay a message's exit.
Sample Request
POST /esa/api/v2.0/quarantine/messages HTTP/1.1
Content-Type: application/json
cache-control: no-cache
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
content-length: 107
Connection: keep-alive
{
"action":"delay",
"delay":"1w",
"mids": [46],
"quarantineName": "Policy",

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
74
 APIs for Email
Sending a Copy of a Message in Quarantine

"quarantineType": "pvo"
}

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Thu, 22 Nov 2018 11:59:07 GMT
Content-type: application/json
Content-Length: 71
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"data": {
"action": "delay",
"totalCount": 1,
"delayedTime": "1 week"
}
}

Sending a Copy of a Message in Quarantine

You can send a copy of a message in quarantine to an email address. The syntax and supported attributes are
given below:

Synopsis POST /api/v2.0/quarantine/messages?resource_attribute

Supported Message ID • "mids": [value]

Resource
Specify the mid of the message.
Attributes

Quarantine "quarantineType": "value"

Type The valid value is pvo.

Quarantine "quarantineName": "value"

Name The valid values are:
Outbreak
Virus
File+Analysis
Unclassified
Policy
<user-defined-quarantine>

Recipients "recipients":["value", "value", ...]

This is a user defined value. Enter email address/s of the recipients.

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
75
 APIs for Email
Sending a Copy of a Message in Quarantine

Request {
"action":"sendCopy",
Body
"mids": [value],
"quarantineName": "value",
"quarantineType": "pvo",
"recipients":["value"]
}

For outbreak, you can add this optional attribute to the message body:
"sendToCisco":<value>

The valid value is true. An example is shown below:

{
"action":"sendCopy",
"mids": [value],
"quarantineName": "value",
"quarantineType": "pvo",
"recipients":["value"],
}

Request Host, Accept, Authorization

Headers

Response Content-Type, Content-Length, Connection

Headers

Example
This example shows a query to send a copy of a message in the Unclassified quarantine to an email address.
Sample Request
POST /esa/api/v2.0/quarantine/messages HTTP/1.1
Content-Type: application/json
cache-control: no-cache
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
content-length: 136
Connection: keep-alive

{
"action":"sendCopy",
"mids": [46],
"quarantineName": "Unclassified",
"quarantineType": "pvo",
"recipients":["admin@cisco.com"]
}

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Thu, 22 Nov 2018 11:53:52 GMT
Content-type: application/json
Content-Length: 49
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
76
 APIs for Email
Downloading an Attachment

Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"data": {
"action": "sendCopy",
"totalCount": 1
}
}

Downloading an Attachment
You can download an attachment accompanying a message in a quarantine. The syntax and supported attributes
are given below:

Synopsis GET /api/v2.0/quarantine/messages?resource_attribute

Supported Message ID • mid=<value>

Resource
Specify the mid of the message.
Attributes

Quarantine quarantineType=<value>
Type The valid value is pvo.

Attachment attachmentId=<value>
ID Specify the attachment ID.

Request Host, Accept, Authorization

Headers

Response Content-Type, Content-Length, Connection

Headers

Example
This example shows a query to download an attachment.
Sample Request
GET /esa/api/v2.0/quarantine/messages/attachment?attachmentId=2&mid=46&quarantineType=pvo
HTTP/1.1
Content-Type: application/json
cache-control: no-cache
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
Connection: keep-alive

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Thu, 22 Nov 2018 12:03:26 GMT
Content-type: application/octet-stream
Content-Disposition: filename="wanacry.exe"
Content-Length: 332511

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
77
 APIs for Email
Deleting Messages

Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

TVqQAAMAAAAEAAAA//8AALgAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
AAAA+AAAAA4fug4AtAnNIbgBTM0hVGhpcyBwcm9ncmFtIGNhbm5vdCBiZSBydW4gaW4gRE9TIG1v
ZGUuDQ0KJAAAAAAAAAAl+pLDYZv8kGGb/JBhm/yQGofwkGKb/JCilKGQdZv8kA6E95Bg

Deleting Messages
You can delete messages that match various attribute. The syntax and supported attributes are given below:

Synopsis DELETE /api/v2.0/quarantine/messages?resource_attribute

Supported Message ID You should use this parameter to effect the delete action.
Resource
• "mids": [<value>]
Attributes
Specify the mid/s of the message/s.

Quarantine "quarantineType": "value"

Type The valid value is pvo.

Quarantine "quarantineName": "<value>"

Name The valid values are:
Outbreak
Virus
File+Analysis
Unclassified
Policy
<user-defined-quarantine>

Request {
"mids": [<mid>],
Body
"quarantineName": "<value>",
"quarantineType": "pvo"
}

Request Host, Accept, Authorization

Headers

Response Content-Type, Content-Length, Connection

Headers

Example
This example shows a query to delete a specific messages in a specific quarantine.
Sample Request
DELETE /esa/api/v2.0/quarantine/messages
HTTP/1.1

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
78
 APIs for Email
Releasing Messages

Content-Type: application/json
cache-control: no-cache
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
content-length: 41
Connection: keep-alive
{
"mids": [112],
"quarantineName": "Policy",
"quarantineType": "pvo"
}

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Thu, 22 Nov 2018 05:48:10 GMT
Content-type: application/json
Content-Length: 47
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"data": {
"action": "delete",
"totalCount": 1
}
}

Releasing Messages
You can release messages that match multiple attributes. The syntax and supported attributes are given below:

Synopsis POST /api/v2.0/quarantine/messages?resource_attribute

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
79
 APIs for Email
Releasing Messages

Supported Message ID You should use this parameter to effect the release action.
Resource
• "mids": [<value>]
Attributes
Specify the mid of the message.

Quarantine "quarantineType": "pvo"

Type The valid value is pvo.

Quarantine "quarantineName": "<value>"

Name The valid values are:
Outbreak
Virus
File+Analysis
Unclassified
Policy
<user-defined-quarantine>

Action "action":"value"

The valid value is release.

Request {
"action":"release",
Body
"mids": [<mid>],
"quarantineName": "<value>",
"quarantineType": "pvo"
}

Request Host, Accept, Authorization

Headers

Response Content-Type, Content-Length, Connection

Headers

Example
This example shows a query to release a specific message with the mid parameter.
Sample Request
POST /esa/api/v2.0/quarantine/messages HTTP/1.1
Content-Type: application/json
cache-control: no-cache
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
content-length: 61
Connection: keep-alive

{
"action":"release",
"mids": [157],
"quarantineName": "Policy",

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
80
 APIs for Email
Viewing the Rule Summary

"quarantineType":"pvo",
}

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Thu, 22 Nov 2018 05:41:10 GMT
Content-type: application/json
Content-Length: 48
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"data": {
"action": "release",
"totalCount": 1
}
}

Viewing the Rule Summary

You can query for the details of messages currently residing in the quarantine. The syntax and supported
attributes are given below:

Synopsis GET /api/v2.0/quarantine/rules?resource_attribute

Supported Quarantine quarantineType=<value>

Resource Type The valid value is pvo.
Attributes

Request Host, Accept, Authorization

Headers

Response Content-Type, Content-Length, Connection

Headers

Example
This example shows a query to retrieve message statistics of messages in quarantine.
Sample Request
GET /esa/api/v2.0/quarantine/rules?quarantineType=pvo HTTP/1.1
cache-control: no-cache
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
Connection: keep-alive

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Thu, 22 Nov 2018 10:33:46 GMT

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
81
 APIs for Email
Searching Based on Rule ID

Content-type: application/json
Content-Length: 264
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"meta": {
"totalAverageMessageSize": "320KB",
"totalNumberOfMessages": 6
},
"data": [
{
"attributes": {
"numberOfMessages": 6,
"capacity": "0.0%",
"ruleId": "Malware: Malware",
"totalSize": "1.9MB",
"ruleDescription": "N/A",
"averageMessageSize": "320KB"
},
"rid": 1
}
]
}

Searching Based on Rule ID

You can search for messages in quarantine that match a specific rule ID. The syntax and supported attributes
are given below:

Synopsis GET /api/v2.0/quarantine/rules_search?resource_attribute

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
82
APIs for Email
Searching Based on Rule ID

Supported Quarantine quarantineType=<value>

Resource Type The valid value is pvo.
Attributes
Rule ID ruleId=<value>

This is a user defined value.

Sorting You can specify the value and the direction order the results.
• orderBy=<value>
The valid value is:
received

• orderDir=<value>
Valid values are:
asc
desc

Lazy You should use both these parameters. If you use either, you will not receive
Loading data in the response.
• offset=<value>
Specify an offset value to retrieve a subset of records starting with the
offset value. Offset works with limit, which determines how many records
to retrieve starting from the offset.
• limit=<value>
Specify the number of records to retrieve.

Request Host, Accept, Authorization

Headers

Response Content-Type, Content-Length, Connection

Headers

Example
This example shows a query to retrieve messages that match rule parameters.
Sample Request
GET /esa/api/v2.0/quarantine/rules_search?limit=25&offset=0&orderBy=
received&orderDir=desc&quarantineType=pvo&ruleId=Malware:+Malware HTTP/1.1
cache-control: no-cache
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
Connection: keep-alive

Sample Response

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
83
 APIs for Email
Searching Based on Rule ID

HTTP/1.1 200 OK
Server: API/2.0
Date: Thu, 22 Nov 2018 10:35:34 GMT
Content-type: application/json
Content-Length: 3013
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"meta": {
"totalCount": 6
},
"data": [
{
"attributes": {
"received": "22 Nov 2018 10:30 (GMT)",
"sender": "usr2@sender.com",
"subject": "[SUSPICIOUS MESSAGE] Test mail.",
"esaHostName": "esa01",
"inQuarantines": "Outbreak",
"scheduledExit": "22 Nov 2018 11:20 (GMT)",
"originatingEsaIp": "10.8.91.15",
"quarantineForReason": [
"Malware: Malware"
],
"esaMid": 476,
"recipient": [
"eriferna@mail.qa.sgg.cisco.com"
],
"quarantineForReasonDict": [
{
"reason": [
"Malware: Malware"
],
"quarantineName": "Outbreak"
}
],
"size": "312.98K"
},
"mid": 191
},
{
"attributes": {
"received": "22 Nov 2018 10:30 (GMT)",
"sender": "usr2@sender.com",
"subject": "[SUSPICIOUS MESSAGE] Test mail.",
"esaHostName": "esa01",
"inQuarantines": "Outbreak",
"scheduledExit": "22 Nov 2018 11:20 (GMT)",
"originatingEsaIp": "10.8.91.15",
"quarantineForReason": [
"Malware: Malware"
],
"esaMid": 474,
"recipient": [
"eriferna@mail.qa.sgg.cisco.com"
],
"quarantineForReasonDict": [
{
"reason": [

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
84
 APIs for Email
Releasing Messages from the Rule Summary

"Malware: Malware"
],
"quarantineName": "Outbreak"
}
],
"size": "312.98K"
},
"mid": 190
},
{
"attributes": {
"received": "22 Nov 2018 10:30 (GMT)",
"sender": "usr2@sender.com",
"subject": "[SUSPICIOUS MESSAGE] Test mail.",
"esaHostName": "esa01",
"inQuarantines": "Outbreak",
"scheduledExit": "22 Nov 2018 11:20 (GMT)",
"originatingEsaIp": "10.8.91.15",
"quarantineForReason": [
"Malware: Malware"
],
"esaMid": 473,
"recipient": [
"eriferna@mail.qa.sgg.cisco.com"
],
"quarantineForReasonDict": [
{
"reason": [
"Malware: Malware"
],
"quarantineName": "Outbreak"
}
],
"size": "312.98K"
},
"mid": 189
}
]
}

Releasing Messages from the Rule Summary

You can release messages from the rule summary that match multiple attributes. The syntax and supported
attributes are given below:

Synopsis POST /api/v2.0/quarantine/rules?resource_attribute

Supported Rule ID • "ruleId": ["value", "value",...]

Resource
Specify the rule IDs.
Attributes

Quarantine quarantineType=<value>
Type The valid value is pvo.

Action "action":"value"

The valid value is release.

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
85
 APIs for Email
Deleting Messages from the Rule Summary

Request {
"action" : "release",
Body
"quarantineType": "pvo",
"ruleId": ["value"]
}

Request Host, Accept, Authorization

Headers

Response Content-Type, Content-Length, Connection

Headers

Example
This example shows a query to release message.
Sample Request
POST /esa/api/v2.0/quarantine/rules
HTTP/1.1
Content-Type: application/json
cache-control: no-cache
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
content-length: 89
Connection: keep-alive

{
"action" : "release",
"quarantineType": "pvo",
"ruleId": ["Malware: Malware"]
}

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Thu, 22 Nov 2018 10:39:29 GMT
Content-type: application/json
Content-Length: 48
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

"data": {
"action": "release",
"totalCount": 3
}
}

Deleting Messages from the Rule Summary

You can delete messages from the rule summary that match specific attributes. The syntax and supported
attributes are given below:

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
86
APIs for Email
Deleting Messages from the Rule Summary

Synopsis DELETE /api/v2.0/quarantine/rules?resource_attribute

Supported Rule ID • "ruleId": ["value", "value",...]

Resource
Specify the rule IDs.
Attributes

Quarantine quarantineType=<value>
Type The valid value is pvo.

Request {
"quarantineType": "pvo",
Body
"ruleId": ["value"]
}

Request Host, Accept, Authorization

Headers

Response Content-Type, Content-Length, Connection

Headers

Example
This example shows a query to delete messages from the rule summary.
Sample Request
DELETE /esa/api/v2.0/quarantine/rules HTTP/1.1
Content-Type: application/json
cache-control: no-cache
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
User-Agent: curl/7.54.0
Accept: */*
Host: esa.cisco.com:6080
accept-encoding: gzip, deflate
content-length: 65
Connection: keep-alive

{
"quarantineType": "pvo",
"ruleId": ["Malware: Malware"]
}

Sample Response
HTTP/1.1 200 OK
Server: API/2.0
Date: Thu, 22 Nov 2018 10:41:14 GMT
Content-type: application/json
Content-Length: 47
Connection: close
Access-Control-Allow-Origin: *
Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONS
Access-Control-Expose-Headers: Content-Disposition, jwtToken

{
"data": {
"action": "delete",
"totalCount": 4

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
87
 APIs for Email
Deleting Messages from the Rule Summary

}
}

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
88
 CHAPTER 3
General Purpose APIs
General purpose configuration queries will have the config resource name as part of the query string. You
can only retrieve configuration information (GET), and cannot perform any changes (POST, DELETE) in
this release. You can specify the device type to indicate the device from which you need the configuration
from Email Security appliance.
This chapter contains the following sections:
• Querying for the System Time, on page 89
• Querying for Managed Email Security Appliances' Information, on page 90
• Retrieving APIs Accessible to a User Role, on page 90
• Health API, on page 91

Querying for the System Time

Sample Request
GET /esa/api/v2.0/config/system_time?
HTTP/1.1
cache-control: no-cache
Authorization: Basic YWRtaW46Q2lzY28xMjMk
Accept: */*
Host: esa.example.com:6080
accept-encoding: gzip, deflate
Connection: keep-alive

Sample Response
HTTP/1.0 200 OK
Server: API/2.0
Date: Thu, 12 Apr 2018 18:06:32 GMT
Content-type: application/json
Content-Length: 121
Connection: close
{
"data": {
"continent": [
"Asia",
"India",
"Kolkata"
],
"time": "Thu Apr 12 23:38:05 2018 IST",
"timezone": "Asia/Kolkata"

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
89
 General Purpose APIs
Querying for Managed Email Security Appliances' Information

}
}

Querying for Managed Email Security Appliances' Information

Sample Request
GET /esa/api/v2.0/config/appliances?
HTTP/1.1
cache-control: no-cache
Authorization: Basic YWRtaW46Q2lzY28xMjMk
Accept: */*
Host: esa.example.com:6080
accept-encoding: gzip, deflate
Connection: keep-alive

Sample Response
HTTP/1.0 200 OK
Server: API/2.0
Date: Thu, 12 Apr 2018 18:09:07 GMT
Content-type: application/json
Content-Length: 341
Connection: close
{
"data": {
"appliances": [
{
"123A45B6C678-1CDEFG2": {
"host_name": "esa11.1",
"ip_address": "10.76.69.29",
"product_type": "ESA"
}
},
{
"123A45B6C678-1CDEFG3": {
"host_name": "esa11.0",
"ip_address": "10.76.68.224",
"product_type": "ESA"
}
},
{
"123A45B6C678-1CDEFG3": {
"host_name": "esa10.0.2",
"ip_address": "10.76.71.63",
"product_type": "ESA"
}
}
]
}
}

Retrieving APIs Accessible to a User Role

You can retrieve a list of APIs that are available for a currently logged in user.

Synopsis GET /api/v2.0/login/privileges

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
90
 General Purpose APIs
Health API

Request Host, Accept, Authorization

Headers

Response Content-Type, Content-Length, Connection

Headers

Sample Request
GET /esa/api/v2.0/login/privileges
HTTP/1.1
cache-control: no-cache
Postman-Token: a7eca7b8-0656-43db-b692-812396a86976
Authorization: Basic YWRtaW46SXJvbnBvcnQxMjMk
Accept: */*
Host: esa.example.com:6080
accept-encoding: gzip, deflate
Connection: keep-alive

Sample Response
HTTP/1.0 200 OK
Server: API/2.0
Date: Thu, 12 Apr 2018 14:17:44 GMT
Content-type: application/json
Content-Length: 4392
Connection: close
{
"data": [
"e_message_tracking_messages",
"e_message_tracking_detail",
"e_message_tracking_availability",
"e_message_tracking_verdict",
"e_message_tracking_dlp_details",
"e_message_tracking_amp_details",
...
...
"e_config_macro_file_types",
"e_config_geo_countries",
"e_config_tracking_query_timeout",
"e_config_spam_quarantine_appearance_details",
"esa_config_users",
"e_config_euq_authentication_method",
"e_config_euq_url_details"
]
}

Health API
You can retrieve information about system health using the health API.

Synopsis GET /api/v2.0/health/

Request Host, Authorization

Headers

Response Content-Type, Content-Length, Connection

Headers

Sample Request

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
91
 General Purpose APIs
Health API

GET /esa/api/v2.0/health
HTTP/1.1
cache-control: no-cache
Postman-Token: a7eca7b8-0656-43db-b692-812396a86976
Authorization: Basic YWRtaW46aXJvbnBvcnQ=
Accept: */*
Host: esa.example.com:6080
accept-encoding: gzip, deflate
Connection: keep-alive

Sample Response
HTTP/1.0 200 OK
Server: API/2.0
Date: Thu, 12 Sept 2019 14:17:44 GMT
Content-type: application/json; charset=UTF-8
Content-Length: 5782
Connection: close
{
"meta": {
"totalCount": -1
},
"data": {
"percentage_ram_utilization": 5,
"messages_in_pvo_quarantines": 0,
"resource_conservation": 0,
"messages_in_workqueue": 0,
"percentage_swap_utilization": 0.0,
"percentage_queue_utilization": 0.0,
"percentage_diskio": 0,
"retry_delivery": "Scheduling all messages for delivery.",
"percentage_cpu_load": 13,
"reset_counters": "Counters have been reset.",
"delivery_status": [

{
"soft_bounces": 0,
"latest_host_status": "Unknown",
"hard_bounces": 0,
"active_recipients": 0,
"destination_domain": "funny.com",
"connections_out": 0,
"delivered_recipients": 10232
},
{
"soft_bounces": 0,
"latest_host_status": "Unknown",
"hard_bounces": 0,
"active_recipients": 0,
"destination_domain": "hello.com",
"connections_out": 0,
"delivered_recipients": 18328
},
{
"soft_bounces": 0,
"latest_host_status": "Unknown",
"hard_bounces": 0,
"active_recipients": 0,
"destination_domain": "sleep.com",
"connections_out": 0,
"delivered_recipients": 18328
},
{
"soft_bounces": 0,
"latest_host_status": "Unknown",

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
92
General Purpose APIs
Health API

"hard_bounces": 0,
"active_recipients": 0,
"destination_domain": "stark.com",
"connections_out": 0,
"delivered_recipients": 27492
},
{
"soft_bounces": 0,
"latest_host_status": "Unknown",
"hard_bounces": 0,
"active_recipients": 0,
"destination_domain": "the.encryption.queue",
"connections_out": 0,
"delivered_recipients": 0
},
{
"soft_bounces": 0,
"latest_host_status": "Up",
"hard_bounces": 0,
"active_recipients": 0,
"destination_domain": "the.euq.queue",
"connections_out": 0,
"delivered_recipients": 79
},
{
"soft_bounces": 0,
"latest_host_status": "Unknown",
"hard_bounces": 0,
"active_recipients": 0,
"destination_domain": "the.euq.release.queue",
"connections_out": 0,
"delivered_recipients": 0
}
],

"system_status": {
"rates": [
{
"total_completed_recipients_rate_five": 8957,
"delivered_recipients_rate_one": 8440,
"messages_received_rate_five": 8824,
"hard_bounced_recipients_rate_one": 0,
"hard_bounced_recipients_rate_fifteen": 0,
"total_completed_recipients_rate_fifteen": 8762,
"recipients_received_rate_one": 8380,
"total_completed_recipients_rate_one": 8440,
"soft_bounced_events_rate_one": 0,
"delivered_recipients_rate_fifteen": 8762,
"recipients_received_rate_fifteen": 8759,
"soft_bounced_events_rate_fifteen": 0,
"messages_received_rate_one": 8380,
"soft_bounced_events_rate_five": 0,
"messages_received_rate_fifteen": 8759,
"delivered_recipients_rate_five": 8957,
"recipients_received_rate_five": 8824,
"hard_bounced_recipients_rate_five": 0
}
],
"version_details": [
{
"build_date": "2020-05-12",
"operating_system": "13.5.1-254",
"install_date": "2020-05-14 02:34:26",
"raid_status": "Unknown",

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
93
 General Purpose APIs
Health API

"serial_number": "4215B52370871114B954-609E45EE2D03",
"model": "C300V"
}
],
"gauges": [
{
"ram_utilization": "5%",
"email_security_appliance": "3%",
"msgs_in_work_queue": 0,
"disk_io_utilization": "0%",
"total_active_recipients": 0,
"current_outgoing_connections": 0,
"total_queue_utilized": "0.0%",
"anti_virus": "0%",
"msgs_in_quarantine": 0,
"quarantine": "0%",
"reporting": "2%",
"space_used_by_quarantine": "0B",
"unattempted": 0,
"logging_disk_utilization": "4%",
"attempted": 0,
"anti_spam": "25%",
"logging_disk_available": "350G",
"current_incoming_connections": 1,
"total_queue_space_used": "1KB",
"overall_cpu_load": "13%",
"dest_objects_in_memory": 7
}
],
"mail_system_status": [
{
"up_since": "4d 2h 12m 24s",
"system_status": "Online",
"oldest_message": "No Messages",
"status_as_of": "Thu May 14 02:32:20 2020 GMT"
}
],
"counters": [
{
"dns_reqs_reset": 7,
"dns_hard_bounces_reset": 0,
"total_hard_bounces_reset": 0,
"dropped_messages_uptime": 0,
"deleted_recipients_uptime": 0,
"net_reqs_lifetime": 13,
"dk_signed_lifetime": 0,
"dropped_messages_reset": 0,
"messages_received_uptime": 862484,
"expired_hard_bounces_uptime": 0,
"rejected_recipients_reset": 0,
"expired_hard_bounces_reset": 0,
"rejected_recipients_uptime": 0,
"expired_lifetime": 6,
"global_unsub_hits_reset": 0,
"recipients_received_uptime": 862484,
"five_xx_hard_bounces_uptime": 0,
"cache_misses_reset": 0,
"filter_hard_bounces_reset": 0,
"five_xx_hard_bounces_lifetime": 0,
"other_hard_bounces_reset": 0,
"dns_hard_bounces_uptime": 0,
"other_hard_bounces_lifetime": 0,
"total_hard_bounces_uptime": 0,
"cache_hits_reset": 7,

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
94
General Purpose APIs
Health API

"rejected_recipients_lifetime": 7,
"dns_reqs_uptime": 862794,
"net_reqs_uptime": 7,
"deleted_recipients_lifetime": 0,
"delivered_recipients_uptime": 862484,
"dns_reqs_lifetime": 1298528,
"exceptions_lifetime": 1298515,
"delivered_recipients_lifetime": 1311178,
"exceptions_reset": 7,
"delivered_recipients_reset": 0,
"total_completed_recipients_lifetime": 1311178,
"cache_misses_lifetime": 13,
"generated_bounce_recipients_uptime": 0,
"total_completed_recipients_uptime": 862484,
"net_reqs_reset": 0,
"pending_requests": 0,
"global_unsub_hits_uptime": 0,
"cache_hits_uptime": 862794,
"dk_signed_uptime": 0,
"other_hard_bounces_uptime": 0,
"last_counter_reset_str": "Mon May 18 04:44:43 2020 GMT",
"generated_bounce_recipients_reset": 0,
"deleted_recipients_reset": 0,
"messages_received_lifetime": 1312025,
"soft_bounced_events_uptime": 0,
"recipients_received_reset": 0,
"filter_hard_bounces_uptime": 0,
"expired_hard_bounces_lifetime": 0,
"recipients_received_lifetime": 1312025,
"total_hard_bounces_lifetime": 0,
"dk_signed_reset": 0,
"filter_hard_bounces_lifetime": 0,
"soft_bounced_events_lifetime": 0,
"dropped_messages_lifetime": 847,
"outstanding_requests": 0,
"cache_hits_lifetime": 1298528,
"generated_bounce_recipients_lifetime": 0,
"cache_misses_uptime": 7,
"soft_bounced_events_reset": 0,
"global_unsub_hits_lifetime": 0,
"total_completed_recipients_reset": 0,
"messages_received_reset": 0,
"expired_uptime": 5,
"five_xx_hard_bounces_reset": 0,
"dns_hard_bounces_lifetime": 0,
"expired_reset": 0,
"exceptions_uptime": 862787
}
]
},
"delivery_status_detail": []
}
}

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
95
 General Purpose APIs
Health API

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
96
 CHAPTER 4
Troubleshooting AsyncOS API
This chapter contains the following sections:
• API Logs, on page 97
• Alerts, on page 97

API Logs
Subscribe to the API logs using System Administration > Log Subscriptions. For instructions, see the Cisco
Email Security Appliances or Online Help.
The following are some of the events that are logged in the API logs:
• API has started or stopped
• Connection to the API failed or closed (after providing response)
• Authentication succeeded or failed
• Request contains errors
• Error while communicating network configuration changes with AsyncOS API

Alerts
Ensure that the appliance is configured to send you alerts related to AsyncOS API. You will receive alerts
when:

Alert Description Type Severity

API has restarted due to an error System Warning

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
97
 Troubleshooting AsyncOS API
Alerts

AsyncOS 13.5.1 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)
98