Cisco AsyncOS API for Email - Getting Started

Guide

Release 1.0
Published: January 27, 2015

Contents
• Overview of Cisco AsyncOS API for Email, page 1
• Prerequisites for Using AsyncOS API, page 2
• Enabling AsyncOS API, page 2
• AsyncOS API Authentication and Authorization, page 3
• AsyncOS API Requests and Responses, page 4
• AsyncOS API Capabilities, page 7
• Troubleshooting AsyncOS API, page 12
• AsyncOS API Reference, page 14

Overview of Cisco AsyncOS API for Email

The Cisco AsyncOS API for Email (or AsyncOS API) is a Representational StateTransfer (REST)-based
set of operations that provide secure and authenticated access to the Email Security appliance reports
and report counters. You can retrieve the Email Security appliance reporting data using this API.

Cisco Systems, Inc.

www.cisco.com
 Prerequisites for Using AsyncOS API

Prerequisites for Using AsyncOS API

To use AsyncOS API, you need:
• An Email Security appliance running on Cisco AsyncOS 9.0 for Email or above.
• 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.
• A client or programming library that initiates requests and receives responses from the AsyncOS
API using HTTP or HTTPS, for example, cURL. The client or programming library must support
JSON to interpret the response from the API.
• Authorization to access the AsyncOS API. See Authorization, page 3.
• AsyncOS API enabled using web interface or CLI. See Enabling AsyncOS API, page 2.

Enabling AsyncOS API

Before You Begin
Make sure that you are authorized to access the IP Interfaces page on the web interface or the
interfaceconfig command on CLI. Only administrators and operators are authorized to access this
page or command.

Procedure

Step 1 Log in to the web interface.

Step 2 Click Network > IP Interfaces.
Step 3 Edit the Management interface.

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

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

Note AsyncOS API communicates using HTTP/1.0.

If you have selected HTTPS and you want to use your own certificate for secure communication, see
Securely Communicating with AsyncOS API, page 3.

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

Cisco AsyncOS API for Email - Getting Started Guide

2
 AsyncOS API Authentication and Authorization

Step 5 Submit and commit your changes.

You can also enable the AsyncOS API using the interfaceconfig command in CLI.

Securely Communicating with AsyncOS API

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

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

Procedure

Step 1 Setup a certificate using the Network > Certificates page on web interface or the certconfig command
in the CLI. For instructions, refer Cisco AsyncOS for Email User Guide or Online Help.
Step 2 Change the HTTPS certificate used by the IP interface to your certificate using the Network > IP
Interfaces page on web interface or the interfaceconfig command in CLI. For instructions, refer Cisco
AsyncOS for Email User Guide or Online Help.
Step 3 Submit and commit your changes.

AsyncOS API Authentication and Authorization

• Authorization, page 3
• Authentication, page 4

Authorization
Email Security appliance users with the following roles can access the AsyncOS API:
• Administrator
• Read-Only Operator
• Operator
• Guest

Note Users from centralized authentication system (LDAP or RADIUS directory) are not authorized to access
the Cisco AsyncOS API for Email. If an LDAP or RADIUS directory user attempts to access the API,
the API sends a 401 error message.

Cisco AsyncOS API for Email - Getting Started Guide

3
 AsyncOS API Requests and Responses

Authentication
API users must submit an Email Security appliance username and password with all the requests to the
API in base64-encoded format. If a request does not include valid credentials in the Authorization
header, the API sends a 401 error message.
You can use any base64 library to convert your credentials into base64-encoded format. The following
table shows an example of base64-encoded credentials:

Item Value
Username administrator

Password Password$123

Credentials administrator:Password$123

Base64-encoded Credentials YWRtaW5pc3RyYXRvcjpQYXNzd29yZCQxMjM=

Note Encoded credentials must be on a single line within the header.

AsyncOS API Requests and Responses

• AsyncOS API Requests, page 4
• AsyncOS API Responses, page 5

AsyncOS API Requests

Requests made to the API have the following characteristics:
• Requests are sent over HTTP or HTTPS
• Each request must contain a valid URI in the following format:
https://{appliance}:{port}/api/v1.0/{resource}?{resource_attributes}, where:
– {appliance}:{port} is the FQDN or the IP address of the appliance and the TCP port number
on which the appliance is listening.
– {resource} is the resource you are attempting to access, for example, reports or counters.
– {resource_attributes} are the supported attributes for a resource, for example, duration,
max, and so on.
• Each request must contain a valid Authorization header in base64 encoded format.
• Each request must be set Accept as: 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 API request as follows:
curl --cacert <ca_cert.crt> -u "username:password"
https://<fqdn>:<port>/api/v1.0/{resource}?{resource_attributes}

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

Cisco AsyncOS API for Email - Getting Started Guide

4
 AsyncOS API Requests and Responses

Request Structure
The following table lists the types of request operations that you can use with the AsyncOS API.

Request Type Description

GET Requests data from a specified resource.

The following table lists the mandatory headers for requests:

Header Values Description

Host {appliance}:{port} The domain name or the IP address of the appliance,
and the TCP port number on which the appliance is
listening.
Accept • application/json Indicates to the server what media type(s) this client is
• */* willing to accept including the resource version.
Authorization Basic {base64-encoded(username:password)} Identifies the authorized user making this request.

AsyncOS API Responses

• Key Components of Responses, page 6
• HTTP Response Codes, page 6

Cisco AsyncOS API for Email - Getting Started Guide

5
 AsyncOS API Requests and Responses

Key Components of Responses

Components Values Description
Status Code and Reason See HTTP Response Codes, HTTP response code and the reason.
page 6.
Message Header Content-Type • application/json Indicates the format of the message body.
Content-Length n/a The length of the response body in octets.
Connection close Options that are desired for the connection.
Message Body n/a The message body is in the format defined by the
Content-Type header. The following are the
components of the message body:
1. URI. The URI you specified in the request to the
API.
Example
"uri":"/api/v1.0/health/"

2. Links or Data
– Links. The list of next level resources in the
hierarchy.
Example
"links":
{"percentage_ram_utilization":
"Percentage...}

– Data. The reporting data provided by the

API based on the specified URI.
Example
"data": {"percentage_diskio": 10}

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

includes three subcomponents—message, code,
and explanation.
Example
"error": {"message": "Unexpected
attribute - starts_with.", "code": "404",
"explanation": "404 = Nothing matches the
given URI."}

Note If the message body contains empty braces

({}), it means that the API could not find any
records matching the query.

HTTP Response Codes

The following is a list of HTTP response codes returned by AsyncOS API:
• 200
• 400

Cisco AsyncOS API for Email - Getting Started Guide

6
 AsyncOS API Capabilities

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

AsyncOS API Capabilities

You can use the AsyncOS API to perform the following actions:
• Retrieve Current Health Parameters of the Appliance, page 7
• Retrieving Email Security Appliance Statistical Reports, page 8
• Accessing Cisco AsyncOS API for Email Inline Help, page 12

Retrieve Current Health Parameters of the Appliance

You can retrieve the current key health parameters of the appliance such as RAM utilization, queue
utilization, messages in work queue, and so on to assess the health of the appliance.

Description Retrieve the key health parameters of the Email Security

appliance.
Synopsis GET /api/v1.0/health
GET /api/v1.0/health/{parameter}
Request Headers Host, Accept, Authorization
Response Headers Content-Type, Content-Length, Connection

Example
Sample Request
GET /api/v1.0/health HTTP/1.0
User-Agent: curl/7.30.0
Host: mail.example.com:8080
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Accept: application/json

Sample Response
HTTP/1.0 200 OK

Cisco AsyncOS API for Email - Getting Started Guide

7
 AsyncOS API Capabilities

Server: EmailAPI/1.0
Date: Wed, 02 Jul 2014 05:07:50 GMT
Content-type: application/json
Content-Length: 246
Connection: close

{
"data":{
"percentage_ram_utilization":10,
"percentage_diskio":20,
"resource_conservation":3,
"messages_in_workqueue":189,
"messages_in_pvo_quarantines":12,
"percentage_swap_utilization":2.0,
"percentage_queue_utilization":5.0,
"percentage_cpu_load":12
},
"uri":"/api/v1.0/health/"
}

Note For more information about these health parameters, access the API inline help using the following URI:
https://{appliance}:{port}/api/v1.0/health/help. See Accessing Cisco AsyncOS API for Email
Inline Help, page 12.

Retrieving Email Security Appliance Statistical Reports

You can retrieve various statistical reports such as Incoming Mail Summary, Virus Types, and so on from
your appliance. Statistical reports can be categorized into three different types:
• Simple Report. This report category counts various events in your appliance such as how many
authentication attempts failed, how many content filters were triggered, and so on for a specified
duration. Examples are mail_authentication_summary and
mail_dlp_outgoing_traffic_summary.

• Top-N Report. This report category counts various events in your appliance against an entity (IP
address, domain name, and so on) for a specified duration and lists the top-N events, where N is a
user specified value. Examples are mail_content_filter_incoming and
mail_dmarc_incoming_traffic_summary.

• Query-based Report. This report category counts various events in your appliance against a
user-specified entity (IP address, domain name, and so on) for a specified duration. Examples are
mail_authentication_incoming_domain and mail_content_filter_outgoing.

For a list of reports under each category, see Statistical Reports, page 14.

Description Retrieve various statistical reports from the Email Security appliance.
Synopsis GET /api/v1.0/stats/report?resource_attribute
GET /api/v1.0/stats/report/counter?resource_attribute

Cisco AsyncOS API for Email - Getting Started Guide

8
 AsyncOS API Capabilities

Supported Resource Simple Report • time_range. Use this attribute to retrieve report(s) for a specified
Attributes duration. This attribute can assume the following values:
– 1h - Aggregate report(s) for the last one hour
– 1d - Aggregate report(s) for the last one day
– duration=YYYY-MM-DDThh:mmTZD/YYYY-MM-DDThh:mmTZD -
Aggregate report(s) for the specified duration. Supported values
of TZD are Z, +hh:mm, or -hh:mm.
Top-N Report • time_range. Use this attribute to retrieve report(s) for a specified
duration. This attribute can assume the following values:
– 1h - Aggregate report(s) for the last one hour
– 1d - Aggregate report(s) for the last one day
– duration=YYYY-MM-DDThh:mmTZD/YYYY-MM-DDThh:mmTZD -
Aggregate report(s) for the specified duration. Supported values
of TZD are Z, +hh:mm, or -hh:mm.
• max=n. Use this attribute to limit the number of results returned by the
report. n is the number of results that you want the report to return and
can assume values from 1 through 1000.
Query-based Report • time_range. Use this attribute to retrieve report(s) for a specified
duration. This attribute can assume the following values:
– 1h - Aggregate report(s) for the last one hour
– 1d - Aggregate report(s) for the last one day
– duration=YYYY-MM-DDThh:mmTZD/YYYY-MM-DDThh:mmTZD -
Aggregate report(s) for the specified duration. Supported values
of TZD are Z, +hh:mm, or -hh:mm.
• entity=value. Use this attribute to retrieve reports based on a
specified entity such as email address, IP address, and so on. You can
choose whether to exactly match the specified text or look for items
starting with the specified text (for instance, starts with "ex" will
match "example.com").

Note The definition of this attribute varies from report type to report
type. For the permissible values of this attribute, see Statistical
Reports, page 14.

To retrieve items starting with the specified text, you must use this
attribute in conjunction with starts_with attribute, for example,
entity=us& starts_with=true.

• starts_with=value. Use this attribute to retrieve items starting with

the specified entity value. This attribute must be used in conjunction
with the entity attribute and value must be set to true, for example,
entity=us&starts_with=true.

• max=n. Use this attribute to limit the number of results returned by the
report. n is the number of results that you want the report to return and
can assume values from 1 through 1000.
Note You cannot use the entity and max=n attributes in the same
request.

Cisco AsyncOS API for Email - Getting Started Guide

9
 AsyncOS API Capabilities

Request Headers Host, Accept, Authorization

Response Headers Content-Type, Content-Length, Connection

Note Use an AND (&) operator to use multiple attributes, for example:
https://{appliance}:{port}/api/v1.0/stats/report/counter?attribute1&attribute2.

Note For more information about statistical reports and counters, access the API inline help. See Accessing
Cisco AsyncOS API for Email Inline Help, page 12.

Examples
• Simple Report Type, page 10
• Top-N Report Type, page 11
• Query-based Report Type, page 11

Simple Report Type

The following example shows how to retrieve aggregate Incoming Mail Summary report for the last one
day.

Sample Request
GET /api/v1.0/stats/mail_incoming_traffic_summary?1d HTTP/1.0
User-Agent: curl/7.30.0
Host: mail.example.com:8080
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Accept: application/json

Sample Response
HTTP/1.0 200 OK
Server: EmailAPI/1.0
Date: Tue, 15 Jul 2014 08:26:46 GMT
Content-type: application/json
Content-Length: 461
Connection: close

{
"data":{
"verif_decrypt_success":0,
"detected_virus":1396438,
"threat_content_filter":106728,
"blocked_invalid_recipient":209054,
"verif_decrypt_fail":0,
"marketing_mail":0,
"detected_amp":0,
"ims_spam_increment_over_case":0,
"total_recipients":827216461,
"detected_spam":1265606,
"total_clean_recipients":1977205,
"blocked_dmarc":0,
"malicious_url":14006,
"total_threat_recipients":825239256,

Cisco AsyncOS API for Email - Getting Started Guide

10
 AsyncOS API Capabilities

"blocked_reputation":822261430
},
"uri":"/api/v1.0/stats/mail_incoming_traffic_summary?1d"
}

Top-N Report Type

The following example shows how to retrieve top five subjects of high volume mails for a specified
duration.

Sample Request
GET
/api/v1.0/stats/mail_subject_stats?duration=2014-04-23T00:00-00:00/2014-10-21T00:00-00:00&
max=5 HTTP/1.0
User-Agent: curl/7.30.0
Host: mail.example.com:8080
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Accept: application/json

Sample Response
HTTP/1.0 200 OK
Server: EmailAPI/1.0
Date: Tue, 15 Jul 2014 08:26:46 GMT
Content-type: application/json
Content-Length: 182
Connection: close

{
"data":{
"num_msgs":{
"Buying judgments":44584,
"Additional Income":39691,
"Why pay more?":46044,
"Message contains":50460,
"Off shore":56954
}
},

"uri":"/api/v1.0/stats/mail_subject_stats?duration=2014-04-23T00:00-00:00/2014-10-21T00:00
-00:00&max=5"
}

Query-based Report Type

The following example shows how to retrieve aggregate Outgoing Sender report for IP addresses starting
with “2001::6” for a specified duration.

Sample Request
GET
/api/v1.0/stats/mail_sender_ip_hostname_detail?duration=2014-04-23T00:00-00:00/2014-10-21T
00:00-00:00&entity=2001::63&starts_with=true HTTP/1.0
User-Agent: curl/7.30.0
Host: mail.example.com:8080
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Accept: application/json

Sample Response
HTTP/1.0 200 OK
Server: EmailAPI/1.0

Cisco AsyncOS API for Email - Getting Started Guide

11
 Troubleshooting AsyncOS API

Date: Thu, 04 Sep 2014 09:27:58 GMT

Content-type: application/json
Content-Length: 633
Connection: close

{
"data":{
"2001::63":{
"detected_virus":2,
"threat_content_filter":0,
"total_dlp_incidents":0,
"total_clean_recipients":4372,
"total_recipients_processed":4374,
"detected_spam":0,
"total_threat_recipients":2
}
"2001::6":{
"detected_virus":2,
"threat_content_filter":0,
"total_dlp_incidents":0,
"total_clean_recipients":1232,
"total_recipients_processed":1234,
"detected_spam":0,
"total_threat_recipients":2
}
},
"uri":"/api/v1.0/stats/mail_sender_ip_hostname_detail?duration=2014-04-23T00:00-00:00/2014
-10-21T00:00-00:00&entity=2001::6&starts_with=true"
}

Accessing Cisco AsyncOS API for Email Inline Help

AsyncOS API provides comprehensive inline help for all of the supported reports and counters. You can
access the inline help of a report or counter by appending /help to its URI.
The following are a few examples:
• GET /api/v1.0/stats/help allows you to retrieve a list of statistical reports and their descriptions.
• GET /api/v1.0/health/help allows you to retrieve a list of key health parameters of the appliance
and their descriptions.
• GET /api/v1.0/stats/mail_incoming_traffic_summary/help allows you to retrieve description
of the Incoming Mail Summary report, supported counters in this report and their descriptions, and
the report category.
• GET /api/v1.0/stats/mail_incoming_traffic_summary/detected_virus/help allows you to
retrieve the description of the counter “detected_virus” in the Incoming Mail Summary report.

Troubleshooting AsyncOS API

• API Logs, page 13
• Alerts, page 13
• Certificate Error while Using cURL, page 13

Cisco AsyncOS API for Email - Getting Started Guide

12
 Troubleshooting AsyncOS API

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

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

Alert Description Type Severity

API has restarted due to an error System Warning
Network configuration or certificate changes made System Critical
using web interface or CLI are not communicated to the
API. See Alert About Network Configuration or
Certificate Changes Not Communicated to AsyncOS
API, page 13.

Alert About Network Configuration or Certificate Changes Not Communicated to AsyncOS API
Problem You receive a critical alert stating that the network configuration or certificate changes made
using web interface or CLI are not communicated to the API.
Solution Try the following:
• Restart the appliance.
• If the problem persists, contact TAC.

Certificate Error while Using cURL

Problem If you are using HTTPS and your own certificate for secure communication with API, on some
operating systems (such as Unix, Ubantu, Mac OS X, and so on) you may receive certificate errors while
requesting API resources using cURL. The following are a few examples:
• curl: (60) SSL certificate problem: Invalid certificate chain
• curl: (77) error setting certificate verify locations

Solution Refer cURL documentation: http://curl.haxx.se/.

Cisco AsyncOS API for Email - Getting Started Guide

13
 AsyncOS API Reference

AsyncOS API Reference

Statistical Reports
The following table provides a list of categories of statistical reports and the reports under each category.

Report Type Reports

Simple Report • mail_authentication_summary
• mail_dlp_outgoing_traffic_summary
• mail_incoming_malware_threat_file_detail_summary
• mail_incoming_traffic_summary
• mail_outgoing_traffic_summary
• mail_security_summary
• mail_sender_group_summary
• mail_system_capacity

Cisco AsyncOS API for Email - Getting Started Guide

14
 AsyncOS API Reference

Report Type Reports

Top-N Report • mail_authentication_incoming_domain_ip
• mail_content_filter_incoming
• mail_dmarc_incoming_traffic_summary
• mail_env_sender_rate_limit
• mail_env_sender_stats
• mail_hvm_msg_filter_stats
• mail_incoming_malware_threat_file_detail
• mail_msg_filter_stats
• mail_sender_group_detail
• mail_subject_stats
• mail_url_category_summary
• mail_url_domain_summary
• mail_url_reputation_summary
• mail_vof_threat_summary
• mail_vof_threats_by_level
• mail_vof_threats_by_threat_type
• mail_vof_threats_by_time_threshold
• mail_vof_threats_by_type
• mail_vof_threats_rewritten_url
Query-specific Report • mail_authentication_incoming_domain
Entity Value: Domain name, for example, abc.com.
• mail_content_filter_outgoing
Entity Value: Name of the outgoing Content
Filter.
• mail_destination_domain_detail
Entity Value: Domain name, for example, abc.com.
• mail_dlp_outgoing_policy_detail
Entity Value: Name of the DLP policy.
• mail_incoming_domain_detail
Entity Value: Domain name, for example, abc.com.
• mail_incoming_ip_hostname_detail
Entity Value: IPv4 or IPv6 address.
• mail_incoming_network_detail
Entity Value: Name of the network owner, for
example Xyz Corporation.
• mail_sender_domain_detail
Entity Value: Domain name, for example, abc.com.
• mail_sender_ip_hostname_detail
Entity Value: IPv4 or IPv6 address.
• mail_users_detail
Entity Value: Email ID of the internal user, for
example, [email protected].
• mail_virus_type_detail
Entity Value: Name of viruses.

Cisco AsyncOS API for Email - Getting Started Guide

15