AsyncOS 13.0 API for Cisco Email Security Appliances ...CONTENTS CHAPTER 1 Overview of AsyncOS API...

AsyncOS 13.0 API for Cisco Email Security Appliances - Getting StartedGuide - GD (General Deployment)First Published: 2020-02-03

Americas HeadquartersCisco Systems, Inc.170 West Tasman DriveSan Jose, CA 95134-1706USAhttp://www.cisco.comTel: 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 WITHTHE 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 ofthe UNIX operating system. All rights reserved. Copyright © 1981, Regents of the University of California.

NOTWITHSTANDING ANY OTHERWARRANTY 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 OFMERCHANTABILITY, 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, WITHOUTLIMITATION, LOST PROFITS OR LOSS OR DAMAGE TO DATA ARISING OUT OF THE USE OR INABILITY TO USE THIS MANUAL, EVEN IF CISCO OR ITS SUPPLIERSHAVE 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, networktopology 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 unintentionaland 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 thisURL: www.cisco.com/go/trademarks. Third-party trademarks mentioned are the property of their respective owners. The use of the word partner does not imply a partnership relationshipbetween Cisco and any other company. (1721R)

© 2020 Cisco Systems, Inc. All rights reserved.

www.cisco.com/go/trademarks

C O N T E N T S

Overview of AsyncOS API for Cisco Email Security Appliances 1C H A P T E R 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

APIs for Email 9C H A P T E R 2

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.0 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)iii

Message Details 24

DLP Details 27

AMP Details 28

URL Details 30

Connection Details 32

Quarantine 34

APIs for Spam Quarantine 34


Retrieving Message Details 37

Deleting Messages 39

Releasing Messages 40

Searching for Safelist and Blocklist Entries 41

Adding, Editing, and Appending Safelist and Blocklist Entries 44

Deleting Safelist or Blocklist Entries 57

APIs for Other Quarantine 61


Retrieving Message Details 68

Move Messages 70

Delaying the Exit of a Message from a Quarantine 71

Sending a Copy of a Message in Quarantine 73

Downloading an Attachment 75

Deleting Messages 76

Releasing Messages 77

Viewing the Rule Summary 79

Searching Based on Rule ID 80

Releasing Messages from the Rule Summary 83

Deleting Messages from the Rule Summary 84

General Purpose APIs 87C H A P T E R 3

Querying for the System Time 87

Querying for Managed Email Security Appliances' Information 88

Retrieving APIs Accessible to a User Role 88

Health API 89

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

Contents

Troubleshooting AsyncOS API 91C H A P T E R 4

API Logs 91

Alerts 91

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

Contents

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

Contents

C H A P T E R 1Overview of AsyncOS API for Cisco EmailSecurity 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 appliancereports, report counters, and tracking. You can retrieve the Email Security appliance reporting and trackingdata using the API. In this release you can query for configuration information. Posting configuration changesis not supported in this release.

For more information, refer to the Swagger API help. To view the API help, access the new web interface ofthe 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 APITo 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 APIusing HTTP or HTTPS, for example, cURL. The client or programming library must support JSON tointerpret 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.0 API for Cisco Email Security Appliances - Getting Started Guide - GD (General Deployment)1

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

Enabling AsyncOS APIBefore You Begin

Make sure that you are authorized to access the IP Interfaces page on the web interface or the interfaceconfigcommand 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.

• You can enable AsyncOS API on any IP interface. However, Cisco recommends that you enable AsyncOSAPI on the Management interface.

• You must not enable APIs on multiple management interface.

Note

Step 4 Under the AsyncOS API (Monitoring) section, depending on your requirements, select HTTP, HTTPS, or both and theports to use.

AsyncOS API communicates using HTTP / 1.1.Note

If you have selected HTTPS and you want to use your own certificate for secure communication, see SecurelyCommunicating with AsyncOS API, on page 2.

Cisco recommends that you always use HTTPS in the production environment. Use HTTP only fortroubleshooting and testing the API.

Note

Step 5 Submit and commit your changes.

Securely Communicating with AsyncOS APIYou can communicate with AsyncOS API over secure HTTP using your own certificate.

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

Note

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


Overview of AsyncOS API for Cisco Email Security AppliancesEnabling AsyncOS API

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 AuthorizationThis section explains about the authentication methods, the user roles which can access APIs, and how toquery for APIs accessible to a user.

• Authentication, on page 3

• Authorization, on page 4

• Retrieving APIs Accessible to a User Role, on page 88

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

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

The user inactivity timeout settings in the appliance applies to the validity of a JWT. The appliance checksevery 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 refreshJWT with API queries, or generate a new one.

Note

POST /esa/api/v2.0/login

Use the syntax below for two factor authentications:POST /esa/api/v2.0/login/two_factor

Synopsis

Use Base64 encoded credentials.{

"data":{

"userName":"YWRtaW4=","passphrase":"aXJvbnBvcnQ="

}}

BodyParameters

Host, Accept, AuthorizationRequestHeaders


Overview of AsyncOS API for Cisco Email Security AppliancesAsyncOS API Authentication and Authorization

Content-Type, Content-Length, ConnectionResponseHeaders

This example shows a query to log in with Base64 encoded credentials, and generate a JWT.

Sample Request

POST /esa/api/v2.0/loginHTTP/1.1Content-Type: application/jsoncache-control: no-cacheUser-Agent: curl/7.54.0Accept: */*Host: esa.cisco.com:6080accept-encoding: gzip, deflatecontent-length: 95Connection: keep-alive{

"data":{

"userName":"YWRtaW4=","passphrase":"aXJvbnBvcnQ="

}}

Sample Response

HTTP/1.1 200 OKServer: API/2.0Date: Mon, 26 Nov 2018 07:22:47 GMTContent-type: application/jsonContent-Length: 618Connection: closeAccess-Control-Allow-Origin: *Access-Control-Allow-Headers: content-type, jwttoken, mid, h, emailAccess-Control-Allow-Credentials: trueAccess-Control-Allow-Methods: GET, POST, DELETE, OPTIONSAccess-Control-Expose-Headers: Content-Disposition, jwtToken

{"data": {

"userName": "admin","is2FactorRedirectRequired": "false","role": "Administrator","email": [],"jwtToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyTmFtZSI6ImFkbWluIiwiaXMyRmFjdG9yQ2hlY2tSZXF1aXJlZCI6ZmFsc2UsImNvb2tpZSI6IlRucEZOVTFFWTNwTlZFMDlDanRMYVRoeENqdFpiV1J6VFVSQk5VMURNWGRpTWxGMVdUSnNlbGt5T0hWWk1qbDBUMnBaZDA5RVFUMEtcbk8xVkhPWHBrUnpGb1lteEtNV0p1VW5CaVYxVjJUbmswTUV4cVFUMEtPMVJVUlhkTlJsazNUVlJKZFUxRE5IZE1WRWw1VFdwek1FMXFcblNUVlNhazVDVDBWRk1rOUVaM2xTUlVreVRYcGtSazFwTVVSTlZFMHpUbFZXUjA1

}}

AuthorizationThe AsyncOS API is a role based system, the scope of API queries is defined by the role of the user. CiscoEmail Security appliance users with the following roles can access the AsyncOS API:

• Administrator

• Operator


Overview of AsyncOS API for Cisco Email Security AppliancesAuthorization

• Technician

• Read-Only Operator

• Guest

• URL Filtering Administrator

• Email Administrator

• Help Desk User

• Externally authenticated users can access the API.

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

Note

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

AsyncOS API RequestsRequests 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 islistening.

• {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:


Overview of AsyncOS API for Cisco Email Security AppliancesAsyncOS API Requests and Responses

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

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

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

AsyncOS API ResponsesThis 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

DescriptionValuesComponents

HTTP response code and the reason.See HTTP ResponseCodes, on page 7.

Status Code and Reason

Indicates the format of the message body.application/jsonContent-TypeMessageHeader

The length of the response body in octets.n/aContent-Length

Options that are desired for the connection.closeConnection


Overview of AsyncOS API for Cisco Email Security AppliancesAsyncOS API Responses

DescriptionValuesComponents

The message body is in the format defined by theContent-Type header. The following are thecomponents of the message body:

1. URI. The URI you specified in the request to theAPI.

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 componentincludes 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 recordsmatching the query.

n/aMessage Body

HTTP Response CodesThe following is a list of HTTP response codes returned by AsyncOS API:

• 200• 202

• 300

• 301

• 307

• 400• 401• 403

• 404


Overview of AsyncOS API for Cisco Email Security AppliancesHTTP Response Codes

• 406• 413• 414• 500• 501• 503• 505

For descriptions of these HTTP response codes, refer the following RFCs:

• RFC1945• RFC7231

AsyncOS API CapabilitiesYou can use the AsyncOS API to retrieve information in the following categories:

• APIs for Email, on page 9

• General Purpose APIs, on page 87


Overview of AsyncOS API for Cisco Email Security AppliancesAsyncOS API Capabilities

C H A P T E R 2APIs for Email

• Reporting APIs, on page 9• Tracking APIs, on page 18• Quarantine, on page 34

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

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

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

Synopsis


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

Aggregate report(s) for the specified duration.

DurationSupportedResourceAttributes

• query_type=graph

Receive data that can be represented as graphs.

• query_type=export

Receive data in the export format.

Query Type

You should use both these parameters. If you use either, you will not receivedata in the response.

• orderBy=<value>

Specify the attribute by which to order the data in the response. Forexample,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.

Sorting


• offset=<value>

Specify an offset value to retrieve a subset of records starting with theoffset value. Offset works with limit, which determines howmany recordsto retrieve starting from the offset.

• limit=<value>

Specify the number of records to retrieve.

LazyLoading

• top=<value>

Specify the number of records with the highest values to return.

DataRetrievalOption

Filtering


APIs for EmailReporting APIs

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 anexact value.

• is

Filter the response data based on the exact value specified.

• device_group_name=<value>

Specify the device group name.

• device_type=esa

Specify the device type. This is a required parameter. All API queries mustbe accompanied with this parameter.

• device_name=<value>

Specify the device name.

Device



ExamplesExamples 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


APIs for EmailExamples

Retrieving a Single Value for a CounterThis example shows a query to retrieve the value of a specific counter from a counter group, with the devicename 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.000ZHTTP/1.1cache-control: no-cacheAuthorization: Basic YWRtaW46aXJvbnBvcnQ=User-Agent: curl/7.54.0Accept: */*Host: esa.cisco.com:6080accept-encoding: gzip, deflateConnection: keep-alive

Sample Response

HTTP/1.1 200 OKServer: API/2.0Date: Sat, 17 Nov 2018 15:58:29 GMTContent-type: application/jsonContent-Length: 96Connection: closeAccess-Control-Allow-Origin: *Access-Control-Allow-Headers: content-type, jwttoken, mid, h, emailAccess-Control-Allow-Credentials: trueAccess-Control-Allow-Methods: GET, POST, DELETE, OPTIONSAccess-Control-Expose-Headers: Content-Disposition, jwtToken

{"meta": {

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

"type": "detected_amp","resultSet": {

"detected_amp": 11}}

}

Retrieving Multiple Values for a CounterThis example shows a query to retrieve values of all counters of a counter group, with the device group nameand 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=esaHTTP/1.1cache-control: no-cacheAuthorization: Basic YWRtaW46aXJvbnBvcnQ=User-Agent: curl/7.54.0Accept: */*Host: esa.cisco.com:6080accept-encoding: gzip, deflateConnection: keep-alive

Sample Response

HTTP/1.1 200 OKServer: API/2.0


APIs for EmailRetrieving a Single Value for a Counter

Date: Sat, 17 Nov 2018 17:39:34 GMTContent-type: application/jsonContent-Length: 580Connection: closeAccess-Control-Allow-Origin: *Access-Control-Allow-Headers: content-type, jwttoken, mid, h, emailAccess-Control-Allow-Credentials: trueAccess-Control-Allow-Methods: GET, POST, DELETE, OPTIONSAccess-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 GroupA counter group may have multiple counters. This example shows a query to retrieve single values for eachcounter 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=2HTTP/1.1cache-control: no-cacheAuthorization: Basic YWRtaW46aXJvbnBvcnQ=User-Agent: curl/7.54.0Accept: */*Host: esa.cisco.com:6080accept-encoding: gzip, deflateConnection: keep-alive

Sample Response



APIs for EmailRetrieving Single Values for Each Counter in a Counter Group

{"meta": {


"type": "recipients_matched","resultSet": {

"recipients_matched": [{"url_rep_neutral": 16},{"url_category": 8}

]}

}}

Retrieving Multiple Values for Multiple CountersThis example shows a query to retrieve multiple values for multiple counters, with offset, limit and devicetype 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=2HTTP/1.1cache-control: no-cacheAuthorization: Basic YWRtaW46aXJvbnBvcnQ=User-Agent: curl/7.54.0Accept: */*Host: esa.cisco.com:6080accept-encoding: gzip, deflateConnection: keep-alive

Sample Response


{"meta": {


"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},


APIs for EmailRetrieving Multiple Values for Multiple Counters

{"vm30bsd0004.ibqa": 0}],"blocked_invalid_recipient": [


],"last_sender_group_name": [

{"pphosted.com": "UNKNOWNLIST"},{"vm30bsd0004.ibqa": "UNKNOWNLIST"}

],"detected_amp": [


],"social_mail": [


],"detected_spam": [


],"blocked_reputation": [


],"total_throttled_recipients": [


],"total_accepted_connections": [


],...

..."threat_content_filter": [


],"marketing_mail": [


],"blocked_dmarc": [


],

"conn_tls_success": [{"pphosted.com": 0},{"vm30bsd0004.ibqa": 5}

],"total_recipients": [


],"conn_tls_fail": [


],"total_threat_recipients": [

{"pphosted.com": 0},


APIs for EmailRetrieving Multiple Values for Multiple Counters

{"vm30bsd0004.ibqa": 49}]

}}

}

Retrieving Multiple Values for Multiple Counters, with Multiple Values for Each CounterThis example shows a query to retrieve multiple values for multiple counters (with multiple values for eachcounter), with filtering, and query type parameters. The graph attribute retrieves time based counter valuesof 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=graphHTTP/1.1cache-control: no-cacheAuthorization: Basic YWRtaW46aXJvbnBvcnQ=User-Agent: curl/7.54.0Accept: */*Host: esa.cisco.com:6080accept-encoding: gzip, deflateConnection: keep-alive

Sample Response


{"meta": {


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


APIs for EmailRetrieving 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},


APIs for EmailRetrieving Multiple Values for Multiple Counters, with Multiple Values for Each Counter

...

...{"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 APIsYou can search for messages or a group of messages that match criteria that you specify. You can retrievemessages' 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

Searching for MessagesYou can search for messages that match multiple attributes. The syntax and supported attributes are givenbelow:

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

See AsyncOS 13.0 API - Addendum to the Getting Started guide for Email SecurityAppliances for more information.

SupportedResourceAttributes




APIs for EmailTracking APIs

https://www.cisco.com/c/en/us/support/security/email-security-appliance/products-programming-reference-guides-list.html


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=20HTTP/1.1cache-control: no-cacheAuthorization: Basic YWRtaW46aXJvbnBvcnQ=User-Agent: curl/7.54.0Accept: */*Host: esa.cisco.com:6080accept-encoding: gzip, deflateConnection: keep-alive

Sample Response

HTTP/1.1 200 OKServer: API/2.0Date: Tue, 20 Nov 2018 09:29:48 GMTContent-type: application/jsonContent-Length: 6693Connection: closeAccess-Control-Allow-Origin: *Access-Control-Allow-Headers: content-type, jwttoken, mid, h, emailAccess-Control-Allow-Credentials: trueAccess-Control-Allow-Methods: GET, POST, DELETE, OPTIONSAccess-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": [

"[email protected]"],"sbrs": "None","serialNumber": "4229CAEC09527FD2570C-F028BAE54A11"


APIs for EmailSearching for Messages

}},{

"attributes": {"direction": "incoming","icid": 103,"senderGroup": "UNKNOWNLIST","sender": "[email protected]","replyTo": "N/A","timestamp": "15 Oct 2018 08:24:39 (GMT)","hostName": "esa01","subject": "message is good","mid": [


"DEFAULT"],"senderIp": "10.8.91.18","verdictChart": "0","senderDomain": "example.com","recipient": [


}},{





}},{

"attributes": {"direction": "incoming","icid": 107,"senderGroup": "UNKNOWNLIST","sender": "[email protected]",



"replyTo": "N/A","timestamp": "15 Oct 2018 08:24:39 (GMT)","hostName": "esa01","subject": "message is good","mid": [




}},{





}},{


100],"isCompleteData": true,



"messageStatus": "Delivered","mailPolicy": [



}},{





}},{







}}

]}

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

GET /api/v2.0/message-tracking/messages?resource_attributeSynopsis




• searchOption=<value>

This attribute has a single permitted value when querying for rejectedconnections. For example:searchOption=rejected_connections

SearchOption

• senderIp=<value>

This is a user defined value. Use the IP address of the server which sendsmessages. For example:senderIp=10.76.70.112

Sender IP


• offset=<value>


• limit=<value>


LazyLoading




APIs for EmailRejected Connections

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=20HTTP/1.1cache-control: no-cacheAuthorization: Basic YWRtaW46aXJvbnBvcnQ=User-Agent: curl/7.54.0Accept: */*Host: esa.cisco.com:6080accept-encoding: gzip, deflateConnection: keep-alive

Sample Response

HTTP/1.1 200 OKServer: API/2.0Date: Tue, 20 Nov 2018 11:26:22 GMTContent-type: application/jsonContent-Length: 436Connection: closeAccess-Control-Allow-Origin: *Access-Control-Allow-Headers: content-type, jwttoken, mid, h, emailAccess-Control-Allow-Credentials: trueAccess-Control-Allow-Methods: GET, POST, DELETE, OPTIONSAccess-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 failusing AUTH mechanism PLAIN with profile failAuthFailoverExists.","messageStatus": "REJECTED","senderIp": "10.76.70.112","senderGroup": "UNKNOWNLIST","sbrs": "None","serialNumber": "848F69E85EEF-6R50TW1"

}}

]}

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

GET /api/v2.0/message-tracking/details?resource_attributeSynopsis


APIs for EmailMessage Details

See AsyncOS 13.0 API - Addendum to the Getting Started guide for Email SecurityAppliances for more information.




Example

This example shows a query to retrieve details of a specific message identified by it's icid, mid and theappliance' 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.000ZHTTP/1.1cache-control: no-cacheAuthorization: Basic YWRtaW46Q2lzY28xMjMkUser-Agent: curl/7.54.0Accept: */*Host: m680q09.ibqa.sgg.cisco.com:6080accept-encoding: gzip, deflateConnection: keep-alive

Sample Response


{"data": {

"messages": {"direction": "outgoing","smtpAuthId": "","sender": "[email protected]","midHeader": "<[email protected]>","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": [

{





"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 7e3dee4dac8f4af561d1108c4b237e5e139bd8d3ddc8518455d3b5fb7e7a70c3).","lastEvent": false

},{

"timestamp": "16 Nov 2018 11:20:12 (GMT)","description": "Message 22125 attachment 'driver_license_germany.txt'

scanned by Advanced MalwareProtection 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": [

"[email protected]"],"showSummaryTimeBox": true,"subject": "Testing"



}}

}

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

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




• serialNumber=<value>

Specify the serial number of the appliance.

SerialNumber


• icid=<value>

Specify the icid of the message.

• mid=<value>

Specify the mid of the message.

Message IDandInjectionConnectionID



Example

This example shows a query to retrieve the DLP details of a specific message identified by it's icid, mid andserial 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.000ZHTTP/1.1cache-control: no-cachePostman-Token: ab16ff7f-847e-4221-a2a2-01de50a33feaAuthorization: Basic YWRtaW46Q2lzY28xMjMkUser-Agent: curl/7.54.0Accept: */*Host: esa.cisco.com:6080accept-encoding: gzip, deflateConnection: keep-alive

Sample Response


APIs for EmailDLP Details


{"data": {

"messages": {"direction": "outgoing","smtpAuthId": "","sender": "[email protected]","midHeader": "<[email protected]>","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": [

"[email protected]"],"subject": "Testing"

}}

}

AMP DetailsYou can retrieve AdvancedMalware Protection action details of messages with different attributes as explainedbelow.


APIs for EmailAMP Details

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






SerialNumber


• icid=<value>


• mid=<value>





Example

This example shows a query to retrieve the AdvancedMalware Protection action details of a specific messageidentified 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.000ZHTTP/1.1cache-control: no-cacheAuthorization: Basic YWRtaW46Q2lzY28xMjMkUser-Agent: curl/7.54.0Accept: */*Host: esa.cisco.com:6080accept-encoding: gzip, deflateConnection: keep-alive

Sample Response



APIs for EmailAMP Details

{"data": {

"messages": {"showAMPDetails": true,"direction": "outgoing","smtpAuthId": "","sender": "[email protected]","midHeader": "<[email protected]>","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, AnalysisScore = 0, sha256 =

7e3dee4dac8f4af561d1108c4b237e5e139bd8d3ddc8518455d3b5fb7e7a70c3,upload_action = Recommended to send the file for analysis","lastEvent": true

}],"senderGroup": "RELAYLIST","recipient": [

"[email protected]"],"subject": "Testing"

}}

}

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

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


APIs for EmailURL Details






SerialNumber


• icid=<value>


• mid=<value>





Example

This example shows a query to retrieve the URL details of a specific message identified by it's icid, mid andserial 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.000ZHTTP/1.1cache-control: no-cacheAuthorization: Basic YWRtaW46Q2lzY28xMjMkUser-Agent: curl/7.54.0Accept: */*Host: esa.cisco.com:6080accept-encoding: gzip, deflateConnection: keep-alive

Sample Response


{


APIs for EmailURL Details

"data": {"messages": {

"direction": "incoming","smtpAuthId": "","sdrAge": "31 years 11 months 18 days","sender": "[email protected]","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": [

"[email protected]"],"subject": "[SUSPICIOUS MESSAGE] [SUSPECTED SPAM] Testing VOF"

}}

}

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

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


APIs for EmailConnection Details






SerialNumber


• icid=<value>


• mid=<value>





Example

This example shows a query to retrieve the connection details of a specific message identified by it's icid, midand 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.000ZHTTP/1.1cache-control: no-cacheAuthorization: Basic YWRtaW46Q2lzY28xMjMkUser-Agent: curl/7.54.0Accept: */*Host: esa.cisco.com:6080accept-encoding: gzip, deflateConnection: keep-alive

Sample Response


{


APIs for EmailConnection 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) onincoming connection (ICID 19213) from sender IP 10.76.70.111. Reverse DNShost 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"

}

QuarantineUsing API queries for quarantine, you can retrieve all information about messages in quarantine. You canaction on the messages by releasing, deleting, and delaying their exit. APIs for quarantine are broadly classifiedunder:

• APIs for Spam Quarantine, on page 34

• APIs for Other Quarantine, on page 61

APIs for Spam QuarantineYou can query for messages in the spam quarantine that match multiple attributes, delete or release messages.


• Retrieving Message Details, on page 37

• Releasing Messages, on page 40

• Deleting Messages, on page 39

• Searching for Safelist and Blocklist Entries, on page 41

• Adding, Editing, and Appending Safelist and Blocklist Entries, on page 44

• Deleting Safelist or Blocklist Entries, on page 57

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

GET /api/v2.0/quarantine/messages?resource_attributeSynopsis


APIs for EmailQuarantine

This is a required parameter. Use this parameter with all API queries.

• startdate=YYYY-MM-DDThh:mm:00.000Z&endDate=YYYY-MM-DDThh:mm:00.000Z

Messages quarantined during this time range.


• quarantineType=<value>

The accepted value is spam.quarantineType=spam

QuarantineType

You can specify the value and the direction order the results.

• orderBy=<value>

Valid values are:

• from_address

• to_address

• subject


Valid values are:

• asc

• desc

Sorting


• offset=<value>


• limit=<value>


LazyLoading

EnvelopeRecipient



• 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

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

Filtering



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.000ZHTTP/1.1cache-control: no-cacheAuthorization: Basic YWRtaW46Q2lzY28xMjMkUser-Agent: curl/7.54.0



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

Sample Response

HTTP/1.1 200 OKServer: API/2.0Date: Wed, 21 Nov 2018 13:19:37 GMTContent-type: application/jsonContent-Length: 39Connection: closeAccess-Control-Allow-Origin: *Access-Control-Allow-Headers: content-type, jwttoken, mid, h, emailAccess-Control-Allow-Credentials: trueAccess-Control-Allow-Methods: GET, POST, DELETE, OPTIONSAccess-Control-Expose-Headers: Content-Disposition, jwtToken

{"meta": {

"totalCount": 1},"data": [

{"attributes": {

"envelopeRecipient": ["[email protected]"

],"toAddress": [

"[email protected]"],"subject": "[SPAM] Spam","date": "21 Nov 2018 14:31 (GMT)","fromAddress": [

"danel"],"size": "1.60K"

},"mid": 170

}]

}

Retrieving Message DetailsYou can retrieve details of a message that match multiple attributes. The syntax and supported attributes aregiven below:



The accepted value is spam.quarantineType=spam

QuarantineType


You must specify the mid of the message to retrieve its details.

• mid=<value>

Message ID


APIs for EmailRetrieving Message Details



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=spamHTTP/1.1cache-control: no-cacheAuthorization: Basic YWRtaW46Q2lzY28xMjMkUser-Agent: curl/7.54.0Accept: */*Host: esa.cisco.com:6080accept-encoding: gzip, deflateConnection: keep-alive

Sample Response

HTTP/1.1 200 OKServer: API/2.0Date: Wed, 21 Nov 2018 13:43:30 GMTContent-type: application/jsonContent-Length: 6491Connection: closeAccess-Control-Allow-Origin: *Access-Control-Allow-Headers: content-type, jwttoken, mid, h, emailAccess-Control-Allow-Credentials: trueAccess-Control-Allow-Methods: GET, POST, DELETE, OPTIONSAccess-Control-Expose-Headers: Content-Disposition, jwtToken

{"data": {

"attributes": {"envelopeRecipient": [

"[email protected]"],"toAddress": [

"Surya Allena <[email protected]>"],"attachments": [],

"messageBody": "Received: from c680q07.ibqa ([10.76.71.196])\r\n by esa.cisco.comwith

ESMTP; 16 Nov 2018 13:58:55 +0000 \nIronPort-SDR:DjDeJA8ZkD90oA9x+n3eGd9Qa/nliZ1dL

MyxB7dsrdq8oTnn8YSi5amR2qihbeq2eJwvVjskf1\r\n KE7TdyCXSokg== \nX-IronPort-AV:

E=Sophos;i=\"5.56,240,1539648000\"; \r\n d=\"scan'\";a=\"22180\" \nIronPort-SDR:

PPj7KDz4Ur8W2ne2fWP/wSOUBwnY3x1XaBz/ryR/98vI6NPraAsA5q7vzUzyaYFpRCWGgfyJaZ\r\n4UIJbt91/

WFccoWcqqO86zz6rYcRASCSM= \nIronPort-PHdr:=?us-ascii?q?9a23=3Az7tnkBDwN1EwuviG0ROD

UyQJP3N1i/DPJgcQr6?=\r\n=?us-ascii?q?AfoPdwSPT7pMbcNUDSrc9gkEXOFd2Cra4c26yO6+jJYi8p2d65",

"date": "16 Nov 2018 13:58 (GMT)",



"fromAddress": ["testuser <[email protected]>"

],"subject": "[SUSPICIOUS MESSAGE] [SUSPECTED SPAM] Testing VOF"

},"mid": 1755

}}

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

DELETE /api/v2.0/quarantine/messages?resource_attributeSynopsis

You should use this parameter to effect the delete action.

• "mids":[<value>]


Message IDSupportedResourceAttributes

"quarantineType":"value"

The valid value is spam.QuarantineType

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

RequestBody



Example

This example shows a query to delete messages.

Sample Request

DELETE /esa/api/v2.0/quarantine/messages HTTP/1.1Content-Type: application/jsoncache-control: no-cacheAuthorization: Basic YWRtaW46aXJvbnBvcnQ=User-Agent: curl/7.54.0Accept: */*Host: esa.cisco.com:6080accept-encoding: gzip, deflatecontent-length: 41Connection: keep-alive

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

Sample Response

HTTP/1.1 200 OKServer: API/2.0


APIs for EmailDeleting Messages

Date: Thu, 22 Nov 2018 05:48:10 GMTContent-type: application/jsonContent-Length: 47Connection: closeAccess-Control-Allow-Origin: *Access-Control-Allow-Headers: content-type, jwttoken, mid, h, emailAccess-Control-Allow-Credentials: trueAccess-Control-Allow-Methods: GET, POST, DELETE, OPTIONSAccess-Control-Expose-Headers: Content-Disposition, jwtToken

{"data": {

"action": "delete","totalCount": 1

}}

Releasing MessagesYou can release a message that matches the mid attribute. The syntax and supported attributes are givenbelow:

POST /api/v2.0/quarantine/messages?resource_attributeSynopsis

You should use this parameter to effect the release action.

• "mids":[<value>]



"action":"value"

The valid value is release.Action

"quarantineType":"value"


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

RequestBody



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.1Content-Type: application/jsoncache-control: no-cacheAuthorization: Basic YWRtaW46aXJvbnBvcnQ=User-Agent: curl/7.54.0


APIs for EmailReleasing Messages

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

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

Sample Response

HTTP/1.1 200 OKServer: API/2.0Date: Thu, 22 Nov 2018 05:41:10 GMTContent-type: application/jsonContent-Length: 48Connection: closeAccess-Control-Allow-Origin: *Access-Control-Allow-Headers: content-type, jwttoken, mid, h, emailAccess-Control-Allow-Credentials: trueAccess-Control-Allow-Methods: GET, POST, DELETE, OPTIONSAccess-Control-Expose-Headers: Content-Disposition, jwtToken

{"data": {

"action": "release","totalCount": 1

}}

Searching for Safelist and Blocklist EntriesYou can retrieve Safelist and Blocklist entries with API queries. The syntax and supported attributes are givenbelow:

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

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

Synopsis


APIs for EmailSearching for Safelist and Blocklist Entries

• action=<value>

Valid value is view.

ActionSupportedResourceAttributes

quarantineType=<value>


viewBy=<value>

The valid values are sender, and recipient.View By

orderBy=<value>

The valid values aresender, and recipient.Order By


• offset=<value>


• limit=<value>


LazyLoading

orderDir=<value>

Valid values are:

• asc

• desc

Ordering

This is only supported for the attribute orderBy=recipient.search=<value>

This is a user defined value.

Search



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 withblocklist 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



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

Sample Response

HTTP/1.1 200 OKServer: API/2.0Date: Fri, 23 Nov 2018 09:08:39 GMTContent-type: application/jsonContent-Length: 126Connection: closeAccess-Control-Allow-Origin: *Access-Control-Allow-Headers: content-type, jwttoken, mid, h, emailAccess-Control-Allow-Credentials: trueAccess-Control-Allow-Methods: GET, POST, DELETE, OPTIONSAccess-Control-Expose-Headers: Content-Disposition, jwtToken

{"meta": {


{"senderList": [

"space.com","xyz.com","abc.com"

],"recipientAddress": "[email protected]"

}]

}

Viewing Safelist and Blocklist entries by sender:

This sample request shows an example query to retrieve blocklist entries by sender. Use the same query withsafelist 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=senderHTTP/1.1Content-Type: application/jsoncache-control: no-cachePostman-Token: 9b9bc6ef-2290-47ce-a84a-077bb805c57fAuthorization: Basic YWRtaW46aXJvbnBvcnQ=User-Agent: PostmanRuntime/7.4.0Accept: */*Host: bgl0090-pod.cisco.com:6080accept-encoding: gzip, deflateConnection: keep-alive




Sample Response


{"meta": {


{"senderList": [

"space.com","xyz.com","abc.com"

],"recipientAddress": "[email protected]"

}]

}

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

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

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

Synopsis


APIs for EmailAdding, Editing, and Appending Safelist and Blocklist Entries

• action=<value>

Valid values are:

• add

• edit

• append

ActionSupportedResourceAttributes



viewBy=<value>

The valid values aresender, and recipient.View By

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

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

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

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

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

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

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

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



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 Body





Examples

• Adding Recipient Safelist Entries, on page 47

• Adding Sender Safelist Entries, on page 48

• Adding Recipient Blocklist Entries, on page 49

• Adding Sender Blocklist Entries, on page 49

• Editing Recipient Safelist Entries, on page 50

• Editing Sender Safelist Entries, on page 51

• Editing Recipient Blocklist Entries, on page 52

• Editing Sender Blocklist Entries, on page 53

• Appending Recipient Safelist Entries, on page 53

• Appending Sender Safelist Entries, on page 54

Adding Recipient Safelist Entries

This sample request shows a query to add a safelist entry.

Sample Request

POST /esa/api/v2.0/quarantine/safelistHTTP/1.1Content-Type: application/jsoncache-control: no-cacheAuthorization: Basic YWRtaW46aXJvbnBvcnQ=User-Agent: curl/7.54.0Accept: */*Host: esa.cisco.com:6080accept-encoding: gzip, deflatecontent-length: 163Connection: keep-alive

{"action": "add","quarantineType": "spam","recipientAddresses": ["[email protected]","[email protected]"],"senderList": ["acme.com"],"viewBy": "recipient"}

Sample Response


{"data": {


APIs for EmailAdding Recipient Safelist Entries

"action": "add","recipientAddresses": [

"[email protected]","[email protected]"

],"senderList": [

"acme.com"]

}}

Adding Sender Safelist Entries


Sample Request

POST /esa/api/v2.0/quarantine/safelist HTTP/1.1Content-Type: application/jsoncache-control: no-cacheAuthorization: Basic YWRtaW46aXJvbnBvcnQ=User-Agent: curl/7.54.0Accept: */*Host: esa.cisco.com:6080accept-encoding: gzip, deflatecontent-length: 155Connection: keep-alive

{"action": "add","quarantineType": "spam","senderAddresses": ["xyz.com","space.com"],"recipientList": ["[email protected]"],"viewBy": "sender"}

Sample Response


{"data": {

"action": "add","recipientList": [

"[email protected]"],"senderAddresses": [

"xyz.com","space.com"

]}

}


APIs for EmailAdding Sender Safelist Entries

Adding Recipient Blocklist Entries

This sample request shows a query to add a blocklist entry.

Sample Request

POST /esa/api/v2.0/quarantine/blocklistHTTP/1.1Content-Type: application/jsoncache-control: no-cachePostman-Token: 55570e07-17fb-436e-9132-9f4998c67e7fAuthorization: Basic YWRtaW46aXJvbnBvcnQ=User-Agent: curl/7.54.0Accept: */*Host: esa.cisco.com:6080accept-encoding: gzip, deflatecontent-length: 163Connection: keep-alive

{"action": "add","quarantineType": "spam","recipientAddresses": ["[email protected]","[email protected]"],"senderList": ["acme.com"],"viewBy": "recipient"}

Sample Response


{"data": {

"action": "add","recipientAddresses": [


],"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.1Content-Type: application/jsoncache-control: no-cacheAuthorization: Basic YWRtaW46aXJvbnBvcnQ=User-Agent: curl/7.54.0


APIs for EmailAdding Recipient Blocklist Entries

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

{"action": "add","quarantineType": "spam","senderAddresses": ["xyz.com","space.com"],"recipientList": ["[email protected]"],"viewBy": "sender"}

Sample Response


{"data": {

"action": "add","recipientList": [



]}

}

Editing Recipient Safelist Entries


Sample Request

POST /esa/api/v2.0/quarantine/safelistHTTP/1.1Content-Type: application/jsoncache-control: no-cachePostman-Token: 55570e07-17fb-436e-9132-9f4998c67e7fAuthorization: Basic YWRtaW46aXJvbnBvcnQ=User-Agent: curl/7.54.0Accept: */*Host: esa.cisco.com:6080accept-encoding: gzip, deflatecontent-length: 163Connection: keep-alive

{"action": "edit","quarantineType": "spam","recipientAddresses": ["[email protected]","[email protected]"],"senderList": ["acme.com"],


APIs for EmailEditing Recipient Safelist Entries

"viewBy": "recipient"}

Sample Response


{"data": {

"action": "edit","recipientAddresses": [


],"senderList": [

"acme.com"]

}}

Editing Sender Safelist Entries


Sample Request


{"action": "edit","quarantineType": "spam","senderAddresses": ["xyz.com","space.com"],"recipientList": ["[email protected]"],"viewBy": "sender"}

Sample Response

HTTP/1.1 200 OKServer: API/2.0Date: Fri, 23 Nov 2018 10:31:28 GMTContent-type: application/jsonContent-Length: 110Connection: closeAccess-Control-Allow-Origin: *Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email


APIs for EmailEditing Sender Safelist Entries

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

{"data": {

"action": "edit","recipientList": [



]}

}

Editing Recipient Blocklist Entries

This sample request shows a query to edit a blocklist entry.

Sample Request


{"action": "edit","quarantineType": "spam","recipientAddresses": ["[email protected]","[email protected]"],"senderList": ["acme.com"],"viewBy": "recipient"}

Sample Response


{"data": {

"action": "edit","recipientAddresses": [


],


APIs for EmailEditing Recipient 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.1Content-Type: application/jsoncache-control: no-cacheAuthorization: Basic YWRtaW46aXJvbnBvcnQ=User-Agent: curl/7.54.0Accept: */*Host: esa.cisco.com:6080accept-encoding: gzip, deflatecontent-length: 155Connection: keep-alive

{"action": "edit","quarantineType": "spam","senderAddresses": ["xyz.com","space.com"],"recipientList": ["[email protected]"],"viewBy": "sender"}

Sample Response


{"data": {

"action": "edit","recipientList": [



]}

}

Appending Recipient Safelist Entries

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

Sample Request


APIs for EmailEditing Sender Blocklist Entries

POST /esa/api/v2.0/quarantine/safelistHTTP/1.1Content-Type: application/jsoncache-control: no-cachePostman-Token: 55570e07-17fb-436e-9132-9f4998c67e7fAuthorization: Basic YWRtaW46aXJvbnBvcnQ=User-Agent: curl/7.54.0Accept: */*Host: esa.cisco.com:6080accept-encoding: gzip, deflatecontent-length: 163Connection: keep-alive

{"action": "append","quarantineType": "spam","recipientAddresses": ["[email protected]","[email protected]"],"senderList": ["acme.com"],"viewBy": "recipient"}

Sample Response


{"data": {

"action": "append","recipientAddresses": [


],"senderList": [

"acme.com"]

}}

Appending Sender Safelist Entries

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

Sample Request



APIs for EmailAppending Sender Safelist Entries

{"action": "append","quarantineType": "spam","senderAddresses": ["xyz.com","space.com"],"recipientList": ["[email protected]"],"viewBy": "sender"}

Sample Response


{"data": {

"action": "append","recipientList": [



]}

}

Appending a Recipient Blocklist Entry

This sample request shows a query to append blocklist entries.

Sample Request


{"action": "append","quarantineType": "spam","recipientAddresses": ["[email protected]","[email protected]"],"senderList": ["acme.com"],"viewBy": "recipient"}

Sample Response


APIs for EmailAppending a Recipient Blocklist Entry


{"data": {

"action": "append","recipientAddresses": [


],"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.1Content-Type: application/jsoncache-control: no-cacheAuthorization: Basic YWRtaW46aXJvbnBvcnQ=User-Agent: curl/7.54.0Accept: */*Host: esa.cisco.com:6080accept-encoding: gzip, deflatecontent-length: 155Connection: keep-alive

{"action": "append","quarantineType": "spam","senderAddresses": ["xyz.com","space.com"],"recipientList": ["[email protected]"],"viewBy": "sender"}

Sample Response


{


APIs for EmailAppending Sender Blocklist Entries

"data": {"action": "append","recipientList": [



]}

}

Deleting Safelist or Blocklist EntriesYou can run API queries to delete safelist or blocklist entries from either the sender or recipient lists.

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

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

Synopsis




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

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

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

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

"viewBy": "value"

Valid values are sender, and recipient

.

View By

Deleting recipient entries:

{"quarantineType": "spam","recipientList": ["value","value"],"viewBy": "recipient"}

Deleting sender entries:

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

Request Body



The following APIs are available:

• Deleting Recipient Safelist Entries, on page 58


APIs for EmailDeleting Safelist or Blocklist Entries

• Deleting Sender Safelist Entries, on page 58

• Deleting Recipient Blocklist Entries, on page 59

• Deleting Sender Blocklist Entries, on page 60

Deleting Recipient Safelist Entries

This sample request shows a query to delete a safelist entry.

Sample Request

DELETE /esa/api/v2.0/quarantine/safelistHTTP/1.1Content-Type: application/jsoncache-control: no-cacheAuthorization: Basic YWRtaW46aXJvbnBvcnQ=User-Agent: curl/7.54.0Accept: */*Host: esa.cisco.com:6080accept-encoding: gzip, deflatecontent-length: 111Connection: keep-alive

{"quarantineType": "spam","recipientList": ["[email protected]","[email protected]"],"viewBy": "recipient"}

Sample Response


{"data": {

"action": "delete","recipientList": [


],"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.1Content-Type: application/jsoncache-control: no-cache


APIs for EmailDeleting Recipient Safelist Entries

Authorization: Basic YWRtaW46aXJvbnBvcnQ=User-Agent: curl/7.54.0Accept: */*Host: esa.cisco.com:6080accept-encoding: gzip, deflatecontent-length: 82Connection: keep-alive

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

Sample Response


{"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/blocklistHTTP/1.1Content-Type: application/jsoncache-control: no-cacheAuthorization: Basic YWRtaW46aXJvbnBvcnQ=User-Agent: curl/7.54.0Accept: */*Host: esa.cisco.com:6080accept-encoding: gzip, deflatecontent-length: 111Connection: keep-alive

{"quarantineType": "spam","recipientList": ["[email protected]","[email protected]"],"viewBy": "recipient"}

Sample Response

HTTP/1.1 200 OKServer: API/2.0Date: Fri, 23 Nov 2018 12:27:40 GMT


APIs for EmailDeleting Recipient Blocklist Entries

Content-type: application/jsonContent-Length: 104Connection: closeAccess-Control-Allow-Origin: *Access-Control-Allow-Headers: content-type, jwttoken, mid, h, emailAccess-Control-Allow-Credentials: trueAccess-Control-Allow-Methods: GET, POST, DELETE, OPTIONSAccess-Control-Expose-Headers: Content-Disposition, jwtToken

{"data": {

"action": "delete","recipientList": [


],"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.1Content-Type: application/jsoncache-control: no-cacheAuthorization: Basic YWRtaW46aXJvbnBvcnQ=User-Agent: curl/7.54.0Accept: */*Host: esa.cisco.com:6080accept-encoding: gzip, deflatecontent-length: 82Connection: keep-alive

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

Sample Response


{"data": {

"action": "delete","totalCount": 1,"senderList": [

"race.com"]


APIs for EmailDeleting Sender Blocklist Entries

}}

APIs for Other QuarantineThese queries will have the quarantineType resource name as part of the query string.

Quarantine queries support search, sorting, offset, and lazy loading.


• Retrieving Message Details, on page 68

• Move Messages, on page 70

• Delaying the Exit of a Message from a Quarantine , on page 71

• Sending a Copy of a Message in Quarantine, on page 73

• Downloading an Attachment, on page 75

• Deleting Messages, on page 76

• Releasing Messages, on page 77

• Viewing the Rule Summary, on page 79

• Searching Based on Rule ID, on page 80

• Releasing Messages from the Rule Summary, on page 83

• Deleting Messages from the Rule Summary, on page 84

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



APIs for EmailAPIs for Other Quarantine

This is a required parameter. All API queries should be accompanied with thisparameter.

• startdate=YYYY-MM-DDThh:mm:00.000Z&endDate=YYYY-MM-DDThh:mm:00.000Z


This parameter specifies the quarantines to search for.

• quarantines=<value, value, ...>

Valid values are:Outbreak

Virus

File+Analysis

Unclassified

Policy

<user-defined-quarantine>

Quarantinesto Search

• 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>


Subject

originatingEsaIp=<value>

You can specify the IP address of the ESA in which the message was processed.OriginatingESA

AttachmentDetails



• attachmentName=<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 isapplicable 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 isapplicable when:

• You choose the range attribute for attachmentSizeFilterBy

attachmentSizeFilterBy=range

• You choose the less_than attribute for attachmentSizeFilterBy

attachmentSizeFilterBy=less_than


The accepted value is pvo.quarantineType=pvo

QuarantineType

Sorting




• orderBy=<value>

Values are:sender

subject

received

scheduledExit

size


Values are:asc

desc


• offset=<value>


• limit=<value>


LazyLoading

• envelopeRecipientFilterBy=<value>


starts_with

ends_with

matches_exactly

does_not_contain

does_not_start_with

does_not_end_with

does_not_match

• envelopeRecipientFilterValue=<value>


EnvelopeRecipient

EnvelopeSender



• envelopeSenderFilterBy=<value>


starts_with

ends_with

matches_exactly

does_not_contain

does_not_start_with

does_not_end_with

does_not_match

• envelopeSenderFilterValue=<value>




Example

This example shows a query to retrieve messages in the other Policy, Virus and Outbreak quarantines, withthe 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.15HTTP/1.1Content-Type: application/jsoncache-control: no-cacheAuthorization: Basic YWRtaW46aXJvbnBvcnQ=User-Agent: curl/7.54.0Accept: */*Host: esa.cisco.com:6080accept-encoding: gzip, deflateConnection: keep-alive

Sample Response

HTTP/1.1 200 OKServer: API/2.0Date: Thu, 22 Nov 2018 09:01:11 GMTContent-type: application/jsonContent-Length: 13093Connection: closeAccess-Control-Allow-Origin: *Access-Control-Allow-Headers: content-type, jwttoken, mid, h, emailAccess-Control-Allow-Credentials: true



Access-Control-Allow-Methods: GET, POST, DELETE, OPTIONSAccess-Control-Expose-Headers: Content-Disposition, jwtToken

{"meta": {


{"attributes": {

"received": "21 Nov 2018 10:10 (GMT)","sender": "[email protected]","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": [

"[email protected]"],"quarantineForReasonDict": [

{"reason": [

"Content Filter: 'url'"],"quarantineName": "Policy"

}],"size": "312.69K"

},"mid": 166

},{

"attributes": {"received": "21 Nov 2018 10:10 (GMT)","sender": "[email protected]","subject": "[SUSPICIOUS MESSAGE] Test mail.","esaHostName": "esa01","inQuarantines": "Policy","scheduledExit": "21 Dec 2018 10:10 (GMT)","originatingEsaIp": "10.8.91.15","quarantineForReason": [



{"reason": [


}],"size": "312.69K"

},"mid": 161

},



{"attributes": {

"received": "21 Nov 2018 10:09 (GMT)","sender": "[email protected]","subject": "[SUSPICIOUS MESSAGE] Test mail.","esaHostName": "esa01","inQuarantines": "Policy","scheduledExit": "21 Dec 2018 10:09 (GMT)","originatingEsaIp": "10.8.91.15","quarantineForReason": [



{"reason": [


}],"size": "312.69K"

},"mid": 153

},{

"attributes": {"received": "20 Nov 2018 12:42 (GMT)","sender": "[email protected]","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": [


{"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": "[email protected]","subject": "[WARNING: ATTACHMENT UNSCANNED]sadsafasd","esaHostName": "esa01","inQuarantines": "Policy","scheduledExit": "20 Dec 2018 12:41 (GMT)",



"originatingEsaIp": "10.8.91.15","quarantineForReason": [

"Message is unscannable by AMP - Service Not Available"],"esaMid": 251,"recipient": [


{"reason": [

"Message is unscannable by AMP - Service Not Available"],"quarantineName": "Policy"

}],"size": "330.19K"

},"mid": 140

}]

}

Retrieving Message DetailsYou can retrieve details of a message that match multiple attributes. The syntax and supported attributes aregiven below:



The accepted value is pvo.quarantineType=pvo

QuarantineType


You must specify the mid of the message to retrieve its details.

• mid=<value>

Message ID



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=pvoHTTP/1.1cache-control: no-cacheAuthorization: Basic YWRtaW46aXJvbnBvcnQ=User-Agent: curl/7.54.0Accept: */*Host: esa.cisco.com:6080



accept-encoding: gzip, deflateConnection: keep-alive

Sample Response


{"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": ["[email protected]"

],"sender": "[email protected]","subject": "[SUSPICIOUS MESSAGE] Test mail."

},"messageBody": "This is a demo mail. http://bit.ly/2zs6KAq \n","headers": "IronPort-SDR:

4Sh6scwkvc+t4BgD5601B/l5cTAMkUtJtFAY+/Sk6YwaaSxL2TOzEKHwsn+6KxG+kV2Zg75sMX DkgdFZYTDPift9VvRsTl0Fz+N6rRgHCB4= X-IPAS-Result:

=?us-ascii?q?A0GSTP/juz9b/+pj4QpOHoMagXSCU4gely0HhysBAQEBA?= 

=?us-ascii?q?QEBeoIOAQEBPQUEAgEFBQEDAwECAgEBLTEkOCyBFxhDiEefIY8MAQEBAQYBA?= 

=?us-ascii?q?QEBAR2PIQEBhH8FiRODF4FVgUqBJ02RGYVLhA55AYEAgTcBAQE?= Subject: [SUSPICIOUS MESSAGE] Test mail. Received: from client.cisco.com(HELO pod1224-client05.ibwsa) ([10.225.99.234]) by pod0090-esa01with ESMTP; 21 Nov 2018 07:01:34 +0000 Message-ID: <194652.955603914-sendEmail@pod1224-client05> From: \"[email protected]\" <usr2@sender



.com> To: \"[email protected]\" <[email protected]> Date: Wed, 21 Nov 2018 10:23:53 +0000 X-Mailer: sendEmail-1.55 MIME-Version: 1.0 Content-Type: multipart/mixed; boundary=\"----MIME delimiter for sendEmail-936308.539779024\""

},"mid": 166

}}

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



• "mids": [<value>]

Specify the mid/s of the message/s.


"quarantineName": "<value>"

The valid value is pvo.QuarantineType

"destinationQuarantineName": "<value>"

The valid values are:Outbreak

Virus

File+Analysis

Unclassified

Policy


DestinationQuarantineName

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

RequestBody



Example

This example shows a query to move a message.

Sample Request

POST /esa/api/v2.0/quarantine/messagesHTTP/1.1


APIs for EmailMove Messages

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

Sample Response


{"data": {

"action": "move","totalCount": 1,"destinationQuarantineName": "Policy"

}}

Delaying the Exit of a Message from a QuarantineYou can delay the exit of messages from a quarantine. The syntax and supported attributes are given below:



APIs for EmailDelaying the Exit of a Message from a Quarantine

• "mids": [value]



"quarantineType": "value"


"quarantineName": "value"


Virus

File+Analysis

Unclassified

Policy


QuarantineName

"delay":"value"

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

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

RequestBody



Example

This example shows a query to delay a message's exit.

Sample Request

POST /esa/api/v2.0/quarantine/messages HTTP/1.1Content-Type: application/jsoncache-control: no-cacheAuthorization: Basic YWRtaW46aXJvbnBvcnQ=User-Agent: curl/7.54.0Accept: */*Host: esa.cisco.com:6080accept-encoding: gzip, deflatecontent-length: 107Connection: keep-alive{"action":"delay","delay":"1w","mids": [46],"quarantineName": "Policy",


APIs for EmailDelaying the Exit of a Message from a Quarantine

"quarantineType": "pvo"}

Sample Response


{"data": {

"action": "delay","totalCount": 1,"delayedTime": "1 week"

}}

Sending a Copy of a Message in QuarantineYou can send a copy of a message in quarantine to an email address. The syntax and supported attributes aregiven below:


• "mids": [value]





"quarantineName": "value"


Virus

File+Analysis

Unclassified

Policy


QuarantineName

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

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


APIs for EmailSending a Copy of a Message in Quarantine

{"action":"sendCopy","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"],}

RequestBody



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.1Content-Type: application/jsoncache-control: no-cacheAuthorization: Basic YWRtaW46aXJvbnBvcnQ=User-Agent: curl/7.54.0Accept: */*Host: esa.cisco.com:6080accept-encoding: gzip, deflatecontent-length: 136Connection: keep-alive

{"action":"sendCopy","mids": [46],"quarantineName": "Unclassified","quarantineType": "pvo","recipients":["[email protected]"]}

Sample Response

HTTP/1.1 200 OKServer: API/2.0Date: Thu, 22 Nov 2018 11:53:52 GMTContent-type: application/jsonContent-Length: 49Connection: closeAccess-Control-Allow-Origin: *Access-Control-Allow-Headers: content-type, jwttoken, mid, h, email


APIs for EmailSending a Copy of a Message in Quarantine

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

{"data": {

"action": "sendCopy","totalCount": 1

}}

Downloading an AttachmentYou can download an attachment accompanying amessage in a quarantine. The syntax and supported attributesare given below:


• mid=<value>





attachmentId=<value>

Specify the attachment ID.AttachmentID



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=pvoHTTP/1.1Content-Type: application/jsoncache-control: no-cacheAuthorization: Basic YWRtaW46aXJvbnBvcnQ=User-Agent: curl/7.54.0Accept: */*Host: esa.cisco.com:6080accept-encoding: gzip, deflateConnection: keep-alive

Sample Response

HTTP/1.1 200 OKServer: API/2.0Date: Thu, 22 Nov 2018 12:03:26 GMTContent-type: application/octet-streamContent-Disposition: filename="wanacry.exe"Content-Length: 332511


APIs for EmailDownloading an Attachment

Connection: closeAccess-Control-Allow-Origin: *Access-Control-Allow-Headers: content-type, jwttoken, mid, h, emailAccess-Control-Allow-Credentials: trueAccess-Control-Allow-Methods: GET, POST, DELETE, OPTIONSAccess-Control-Expose-Headers: Content-Disposition, jwtToken

TVqQAAMAAAAEAAAA//8AALgAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA+AAAAA4fug4AtAnNIbgBTM0hVGhpcyBwcm9ncmFtIGNhbm5vdCBiZSBydW4gaW4gRE9TIG1vZGUuDQ0KJAAAAAAAAAAl+pLDYZv8kGGb/JBhm/yQGofwkGKb/JCilKGQdZv8kA6E95Bg

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

DELETE /api/v2.0/quarantine/messages?resource_attributeSynopsis



Specify the mid/s of the message/s.






Virus

File+Analysis

Unclassified

Policy


QuarantineName

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

RequestBody



Example

This example shows a query to delete a specific messages in a specific quarantine.

Sample Request

DELETE /esa/api/v2.0/quarantine/messagesHTTP/1.1


APIs for EmailDeleting Messages

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

Sample Response


{"data": {


}}

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




You should use this parameter to effect the release action.




"quarantineType": "pvo"




Virus

File+Analysis

Unclassified

Policy


QuarantineName

"action":"value"


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

RequestBody



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.1Content-Type: application/jsoncache-control: no-cacheAuthorization: Basic YWRtaW46aXJvbnBvcnQ=User-Agent: curl/7.54.0Accept: */*Host: esa.cisco.com:6080accept-encoding: gzip, deflatecontent-length: 61Connection: keep-alive

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



"quarantineType":"pvo",}

Sample Response


{"data": {

"action": "release","totalCount": 1

}}

Viewing the Rule SummaryYou can query for the details of messages currently residing in the quarantine. The syntax and supportedattributes are given below:

GET /api/v2.0/quarantine/rules?resource_attributeSynopsis






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.1cache-control: no-cacheAuthorization: Basic YWRtaW46aXJvbnBvcnQ=User-Agent: curl/7.54.0Accept: */*Host: esa.cisco.com:6080accept-encoding: gzip, deflateConnection: keep-alive

Sample Response

HTTP/1.1 200 OKServer: API/2.0Date: Thu, 22 Nov 2018 10:33:46 GMT


APIs for EmailViewing the Rule Summary

Content-type: application/jsonContent-Length: 264Connection: closeAccess-Control-Allow-Origin: *Access-Control-Allow-Headers: content-type, jwttoken, mid, h, emailAccess-Control-Allow-Credentials: trueAccess-Control-Allow-Methods: GET, POST, DELETE, OPTIONSAccess-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 IDYou can search for messages in quarantine that match a specific rule ID. The syntax and supported attributesare given below:

GET /api/v2.0/quarantine/rules_search?resource_attributeSynopsis


APIs for EmailSearching Based on Rule ID




ruleId=<value>

This is a user defined value.Rule ID


• orderBy=<value>

The valid value is:received


Valid values are:asc

desc

Sorting


• offset=<value>


• limit=<value>


LazyLoading



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.1cache-control: no-cacheAuthorization: Basic YWRtaW46aXJvbnBvcnQ=User-Agent: curl/7.54.0Accept: */*Host: esa.cisco.com:6080accept-encoding: gzip, deflateConnection: keep-alive

Sample Response




{"meta": {


{"attributes": {

"received": "22 Nov 2018 10:30 (GMT)","sender": "[email protected]","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": [


{"reason": [

"Malware: Malware"],"quarantineName": "Outbreak"

}],"size": "312.98K"

},"mid": 191

},{

"attributes": {"received": "22 Nov 2018 10:30 (GMT)","sender": "[email protected]","subject": "[SUSPICIOUS MESSAGE] Test mail.","esaHostName": "esa01","inQuarantines": "Outbreak","scheduledExit": "22 Nov 2018 11:20 (GMT)","originatingEsaIp": "10.8.91.15","quarantineForReason": [



{"reason": [




}],"size": "312.98K"

},"mid": 190

},{

"attributes": {"received": "22 Nov 2018 10:30 (GMT)","sender": "[email protected]","subject": "[SUSPICIOUS MESSAGE] Test mail.","esaHostName": "esa01","inQuarantines": "Outbreak","scheduledExit": "22 Nov 2018 11:20 (GMT)","originatingEsaIp": "10.8.91.15","quarantineForReason": [



{"reason": [


}],"size": "312.98K"

},"mid": 189

}]

}

Releasing Messages from the Rule SummaryYou can release messages from the rule summary that match multiple attributes. The syntax and supportedattributes are given below:

POST /api/v2.0/quarantine/rules?resource_attributeSynopsis

• "ruleId": ["value", "value",...]

Specify the rule IDs.

Rule IDSupportedResourceAttributes



"action":"value"



APIs for EmailReleasing Messages from the Rule Summary

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

RequestBody



Example

This example shows a query to release message.

Sample Request

POST /esa/api/v2.0/quarantine/rulesHTTP/1.1Content-Type: application/jsoncache-control: no-cacheAuthorization: Basic YWRtaW46aXJvbnBvcnQ=User-Agent: curl/7.54.0Accept: */*Host: esa.cisco.com:6080accept-encoding: gzip, deflatecontent-length: 89Connection: keep-alive

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

Sample Response


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

}}

Deleting Messages from the Rule SummaryYou can delete messages from the rule summary that match specific attributes. The syntax and supportedattributes are given below:


APIs for EmailDeleting Messages from the Rule Summary

DELETE /api/v2.0/quarantine/rules?resource_attributeSynopsis

• "ruleId": ["value", "value",...]

Specify the rule IDs.

Rule IDSupportedResourceAttributes



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

RequestBody



Example

This example shows a query to delete messages from the rule summary.

Sample Request

DELETE /esa/api/v2.0/quarantine/rules HTTP/1.1Content-Type: application/jsoncache-control: no-cacheAuthorization: Basic YWRtaW46aXJvbnBvcnQ=User-Agent: curl/7.54.0Accept: */*Host: esa.cisco.com:6080accept-encoding: gzip, deflatecontent-length: 65Connection: keep-alive

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

Sample Response


{"data": {




}}



C H A P T E R 3General Purpose APIs

General purpose configuration queries will have the config resource name as part of the query string. Youcan only retrieve configuration information (GET), and cannot perform any changes (POST, DELETE) inthis release. You can specify the device type to indicate the device from which you need the configurationfrom Email Security appliance.


• Querying for the System Time, on page 87• Querying for Managed Email Security Appliances' Information, on page 88• Retrieving APIs Accessible to a User Role, on page 88• Health API, on page 89

Querying for the System TimeSample Request

GET /esa/api/v2.0/config/system_time?HTTP/1.1cache-control: no-cacheAuthorization: Basic YWRtaW46Q2lzY28xMjMkAccept: */*Host: esa.example.com:6080accept-encoding: gzip, deflateConnection: keep-alive

Sample Response

HTTP/1.0 200 OKServer: API/2.0Date: Thu, 12 Apr 2018 18:06:32 GMTContent-type: application/jsonContent-Length: 121Connection: close{

"data": {"continent": [

"Asia","India","Kolkata"

],"time": "Thu Apr 12 23:38:05 2018 IST","timezone": "Asia/Kolkata"


}}

Querying for Managed Email Security Appliances' InformationSample Request

GET /esa/api/v2.0/config/appliances?HTTP/1.1cache-control: no-cacheAuthorization: Basic YWRtaW46Q2lzY28xMjMkAccept: */*Host: esa.example.com:6080accept-encoding: gzip, deflateConnection: keep-alive

Sample Response


"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 RoleYou can retrieve a list of APIs that are available for a currently logged in user.

GET /api/v2.0/login/privilegesSynopsis


General Purpose APIsQuerying for Managed Email Security Appliances' Information



Sample Request

GET /esa/api/v2.0/login/privilegesHTTP/1.1cache-control: no-cachePostman-Token: a7eca7b8-0656-43db-b692-812396a86976Authorization: Basic YWRtaW46SXJvbnBvcnQxMjMkAccept: */*Host: esa.example.com:6080accept-encoding: gzip, deflateConnection: keep-alive

Sample Response


"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 APIYou can retrieve information about system health using the health API.

GET /api/v2.0/health/Synopsis

Host, AuthorizationRequestHeaders


Sample Request


General Purpose APIsHealth API

GET /esa/api/v2.0/healthHTTP/1.1cache-control: no-cachePostman-Token: a7eca7b8-0656-43db-b692-812396a86976Authorization: Basic YWRtaW46SXJvbnBvcnQxMjMkAccept: */*Host: esa.example.com:6080accept-encoding: gzip, deflateConnection: keep-alive

Sample Response

HTTP/1.0 200 OKServer: API/2.0Date: Thu, 12 Sept 2019 14:17:44 GMTContent-type: application/jsonContent-Length: 260Connection: close{"data": {"percentage_ram_utilization": 1,"percentage_diskio": 0,"resource_conservation": 0,"messages_in_workqueue": 0,"messages_in_pvo_quarantines": 0,"percentage_swap_utilization": 0,"percentage_queue_utilization": 0,"percentage_cpu_load": 18}}


General Purpose APIsHealth API

C H A P T E R 4Troubleshooting AsyncOS API


• API Logs, on page 91• Alerts, on page 91

API LogsSubscribe to the API logs using System Administration >Log Subscriptions. For instructions, see the CiscoEmail 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

AlertsEnsure that the appliance is configured to send you alerts related to AsyncOS API. You will receive alertswhen:

SeverityTypeAlert Description

WarningSystemAPI has restarted due to an error



Troubleshooting AsyncOS APIAlerts

Date post:	29-Sep-2020
Category:	Documents
Upload:	others
View:	11 times
Download:	0 times

AsyncOS 13.0 API for Cisco Email Security Appliances ...CONTENTS CHAPTER 1 Overview of AsyncOS API...

Documents