Getting Started

Base URL

For the Authorization of the Secure Email Threat Defense API mentioned, use a URL that begins with the fully qualified domain name (FQDN) of the Secure Email Threat Defense API Servers. There is a European and an American API service, and you would use the corresponding service depending on whether your Email Threat Defense instance is in the Americas or Europe, Middle East, and Africa (EMEA) data center.

Americas API endpoint:

Code Snippet

Copyhttps://api.us.etd.cisco.com/

Europe API endpoint:

Code Snippet

Copyhttps://api.de.etd.cisco.com/

Australia API endpoint:

Code Snippet

Copyhttps://api.au.etd.cisco.com/

India API endpoint:

Code Snippet

Copyhttps://api.in.etd.cisco.com/

API Features

The Secure Email Threat Defense API features can be divided into five groups:

Authentication – This API allows you to use the client credentials generated on the ETD admin page to create a JWT token for the Secure Email Threat Defense API. For more information, refer to Authentication section.

Message Search – This API allows you to search message information within a period, with or without filters narrowing down the results.

Remediation and Reclassification API - This API allows customers to remediate and reclassify large batches of messages to respond to threats.

Status - This API allows you to check the status of the message.

Reporting - This API empowers customers to create their reports and dashboards, enabling better management of their clients.

Message Search API

Message Search API retrieves the message information from ETD using the JWT created by the Authentication API.

Available Message Search API endpoints are:

Americas API endpoint:

Code Snippet

Copyhttps://api.us.etd.cisco.com/v1/messages/search

Europe API endpoint:

Code Snippet

Copyhttps://api.de.etd.cisco.com/v1/messages/search

Australia API endpoint:

Code Snippet

Copyhttps://api.au.etd.cisco.com/v1/messages/search

India API endpoint:

Code Snippet

Copyhttps://api.in.etd.cisco.com/v1/messages/search

Example of a Message Search API request using CURL:

curl

Copy  curl -X POST \ 

https:// api.us.etd.cisco.com/v1/messages/search -H 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjEDFHSHgxMzEsImlhdCI6MTY4MTkxNDUzMSwic3ViIjoi YXBpLWSTYWKLdCIsImF1ZCI6InB1YmxpYy1hcGDFGFDGllbnRJZCI6ImVjNzQxZGZhLWUzMzk 
tNGY1NS1hMGZmLTSDFGSFM2IwN2NlMSIsInRlbmFudElkIjoiY2M4YjkwZjQtMSDHSFH0xMWVhLWFmMDgtOGMxNjQ1NGZGFHJ6FJD4 
.ZMMoPWCr3xq2dd9CRbbcHI836Nk4B1o0d5pIfY_JZ2c' \ 
  -H 'x-api-key: apikeyTest’ \

  -H 'cache-control: no-cache' \ 

  -H 'content-type: application/json' \ 

  -d '{"timestamp":["2023-12-01T09:34:05.361Z","2023-12-19T17:34:05.361Z"]}'

Note:

Please note that the Timestamp field is mandatory in the request body. It is an ISO 8601 formatted date-time string range, for example, ["2023-02-01T12:00:00Z", "2023-02-20T23:59:59Z"]. The start and end dates are inclusive. Timestamps should be in the UTC timezone only. The first timestamp should be smaller than the second.
The Message search API allows searches for a period of 32 days. The date range should not exceed 90 days in the past.
The current page limit is 100 messages per request. You can use the nextPage token to navigate if you get more than 100 results on your query.

Responses

Using the API may produce different responses for the HTTP request. Here are the expected results:

Code	Message	Description
200	Success	The request was process and executed.
400	Bad Request	The request is misformatted or there is not enough information to authenticate the request.
401	Unauthorized	Authorization information is either missing, incomplete, or incorrect.
404	Not Found	The requested resource does not exist.
500	Internal Server Error	The request was not processed successfully, or no better response to the request is available.
502		Bad Gateway

Remediation and Reclassification API

The Remediation and Reclassification API allows customers to remediate and reclassify large batches of messages to respond to threats. Customers can remediate and reclassify 100 messages at a time, allowing them to move messages quickly during a large-scale attack that can come in 1000 or more messages across their environment.

Available Remediation and Reclassification API endpoints are:

Americas API endpoint:

Code Snippet

Copyhttps://api.us.etd.cisco.com/v1/messages/move

Europe API endpoint:

Code Snippet

Copyhttps://api.de.etd.cisco.com/v1/messages/move

Australia API endpoint:

Code Snippet

Copyhttps://api.au.etd.cisco.com/v1/messages/move

India API endpoint:

Code Snippet

Copyhttps://api.in.etd.cisco.com/v1/messages/move

Example of a Remediation and Reclassification API request using CURL:

curl

Copy  curl --location --request POST 'https://api.beta.etd.cisco.com/v1/messages/move' \
--header 'Authorization: Bearer eyJhbGciOMxNTQ5In0.fx1ceRhRbOfrky609JQCVpU_f_RACjdADMAOn4aSQGg' \
--header 'x-api-key: apikeyTest’ \
--header 'Content-Type: application/json' \
--data-raw '{"folder":"trash", "verdict":"spam", "ids":["c99f1f30-89ea-4306-bc44-1f9475ffaa1a"]}'

Note:

The user needs to pass the message IDs as a list separated by commas. They can get the message IDs from the "id" field in the Message Search public API.
Both "folder" and "verdict" are compulsory in the request body.
A maximum of 100 message IDs at once can be remediated and reclassified using the API.

Sample Response:

rpc

Copy{
    "data": {
        "messageMoveStatus": [
            {
                "id": "2",
                "queueSuccess": false,
                "reason": "message not found"
            },
            {
                "id": "cbfeefa7-f738-4bdd-999a-3993ad92caa9",
                "queueSuccess": true
            }
        ],
        "messageVerdictStatus": [
            {
                "id": "2",
                "queueSuccess": false,
                "reason": "message not found"
            },
            {
                "id": "cbfeefa7-f738-4bdd-999a-3993ad92caa9",
                "queueSuccess": true
            }
        ]
    }
}

Common error response:

Case	Error Code
All message ids not found	404
Tenant does not have Microsoft 365 write permission	403

Status API

Customers can use the Status API to check the status of the message. It is a generic API that can return up to five last statuses of the message. After remediating and reclassifying the message using the Move API, users can check the status of the message using this API after some time.

Americas API endpoint:

Code Snippet

Copyhttps://api.us.etd.cisco.com/v1/messages/status

Europe API endpoint:

Code Snippet

Copyhttps://api.de.etd.cisco.com/v1/messages/status

Australia API endpoint:

Code Snippet

Copyhttps://api.au.etd.cisco.com/v1/messages/status

India API endpoint:

Code Snippet

Copyhttps://api.in.etd.cisco.com/v1/messages/status

Sample Status API request using CURL:

curl

Copy  curl --location --request POST 'https://api.beta.etd.cisco.com/v1/messages/status' \
--header 'x-api-key: apikeyTest’ \  
--header 'Authorization: Bearer <Bearer Token>' \
--header 'Content-Type: application/json' \
--data-raw '{"id":"c99f1f30-89ea-4306-bc44-1f9475ffaa1a"}'

Sample Response:

rpc

Copy{
    "data": {
        "actions": [
            {
                "timestamp": "2023-10-20T05:36:35.61606439Z",
                "action": "move",
                "folder": "inbox",
                "initiator": "api",
                "status": "succeeded",
                "publicApiClientId": "0487b580-801f-418c-b40f-9cb9cd023071"
            },
            {
                "timestamp": "2023-10-20T05:35:45.44136178Z",
                "action": "move",
                "folder": "quarantine",
                "userId": "e90a35aa-8db0-4ac4-9e5c-a13373902878",
                "initiator": "manual",
                "status": "succeeded"
            },
            {
                "timestamp": "2023-10-20T05:34:53.093442228Z",
                "action": "move",
                "folder": "trash",
                "initiator": "api",
                "status": "succeeded",
                "publicApiClientId": "0487b580-801f-418c-b40f-9cb9cd023071"
            }
        ],
        "verdicts": [
            {
                "timestamp": "2023-10-20T05:36:07Z",
                "verdict": "spam",
                "reclassifiedBy": "api",
                "publicApiClientId": "0487b580-801f-418c-b40f-9cb9cd023071"
            },
            {
                "timestamp": "2023-10-20T05:35:44.80385058Z",
                "verdict": "phishing",
                "reclassifiedBy": "user",
                "userId": "e90a35aa-8db0-4ac4-9e5c-a13373902878"
            }
        ],
        "id": "cbfeefa7-f738-4bdd-999a-3993ad92caa9"
    }
}

Note:

Users can only pass one emailId in the request body.
If the user remediated a message using the Move API, the initiator field value in the response would be "api".
If the user reclassified a message using the Move API, the reclassifiedBy field value in the response would be "api" and the publicApiClientId would indicate which id performed the action.

Reporting API

The Reporting API empowers customers to create their reports and dashboards, enabling better management of their clients. This enhanced capability increases sellers' ability to attract customers and provides customers with more information on the usage of the ETD. The API allows search for a period of 90 days.

Currently Secure Email Threat Defence has five reporting APIs -

Total messages scanned aggregated by directions
Total traffic by verdicts
Total messages by retropective verdicts
Top 10 Targets by threat along with conviction count
Top 10 Senders by threat

Total message scanned aggregated by directions, total traffic by verdicts, and total messages by retroVerdicts

Total message scanned aggregated by directions, Total traffic by verdicts, and Total messages by retroVerdicts reporting APIs allow you to generate reports on the total number of messages scanned by the ETD, aggregated based on direction, verdicts, and retrospective verdicts.

Available API endpoints are:

Americas API endpoint:

Code Snippet

Copyhttps://api.us.etd.cisco.com/v1/messages/report

Europe API endpoint:

Code Snippet

Copyhttps://api.de.etd.cisco.com/v1/messages/report

Australia API endpoint:

Code Snippet

Copyhttps://api.au.etd.cisco.com/v1/messages/report

India API endpoint:

Code Snippet

Copyhttps://api.in.etd.cisco.com/v1/messages/report

Sample request using CURL:

curl

Copy  curl --location 'https://api.de.etd.cisco.com/v1/messages/report' \
--header 'x-api-key: apikeyTest’ \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOtMzQ2OGZhNjYwNWVmIn0.GuVau-3aTtYAZeQL0iJOBRif_Ir7DKuE4BKuK-DsCyA' \
--data '    {
    "aggregationInterval": "1d",
    "timestamp": [
        "2023-11-19T12:00:00Z",
        "2023-11-20T23:59:59Z"
    ],
    "aggregateBy": "directions"
    }'

Note:

aggregateBy supports direction, verdicts, and retroVerdicts depending on the user's choice of the report.
aggregationInterval supports 1hr, 1d, or 30d.
For the intervals longer than seven days, aggreagtionInterval can be 1d or 30d.
The API allows searches for a period of 90 days. The date range should not exceed 90 days in the past.

Sample Response of total message scanned by direction:

rpc

Copy{
    "data": {
        "aggregationInterval": "1h",
        "totalMessages": 3,
        "aggregations": [
            {
                "startTimestamp": "2023-11-19T12:00:00.000Z",
                "messageCount": 2,
                "messages": {
                    "incoming": 0,
                    "outgoing": 0,
                    "internal": 2
                }
            },
            {
                "startTimestamp": "2023-11-19T13:00:00.000Z",
                "messageCount": 1,
                "messages": {
                    "incoming": 1,
                    "outgoing": 0,
                    "internal": 0
                }
            }
        ]
    }
}

Sample Response of total traffic by verdicts:

rpc

Copy{

    "data": {
        "aggregationInterval": "1d",
        "totalMessages": 45,
        "aggregations": [
            {
                "startTimestamp": "2023-11-19T00:00:00.000Z",
                "messageCount": 42,
                "messages": {
                    "malicious": 28,
                    "spam": 6,
                    "phishing": 6,
                    "graymail": 0,
                    "bec": 0,
                    "scam": 2
                }
            },
            {
                "startTimestamp": "2023-11-20T00:00:00.000Z",
                "messageCount": 3,
                "messages": {
                    "malicious": 0,
                    "spam": 3,
                    "phishing": 0,
                    "graymail": 0,
                    "bec": 0,
                    "scam": 0
                }
            }
        ]
    }
}

Sample Response of total messages by retrospective verdicts:

rpc

Copy{

    "data": {
        "aggregationInterval": "1d",
        "totalMessages": 45,
        "aggregations": [
            {
                "startTimestamp": "2024-01-19T00:00:00.000Z",
                "messageCount": 42,
            },
            {
                "startTimestamp": "2024-01-20T00:00:00.000Z",
                "messageCount": 3,  
            }
        ]
    }
}

Top 10 Targets by threat along with conviction count

This reporting API enables you to identify the top 10 target addresses that received the most threat messages and their respective conviction counts over the past 90 days.

Available API endpoints are:

Americas API endpoint:

Code Snippet

Copyhttps://api.us.etd.cisco.com/v1/messages/report/top

Europe API endpoint:

Code Snippet

Copyhttps://api.de.etd.cisco.com/v1/messages/report/top

Australia API endpoint:

Code Snippet

Copyhttps://api.au.etd.cisco.com/v1/messages/report/top

India API endpoint:

Code Snippet

Copyhttps://api.in.etd.cisco.com/v1/messages/report/top

Sample request using CURL:

curl

Copy  curl --location 'https://api.de.etd.cisco.com/v1/messages/report/top' \
--header 'x-api-key: apikeyTest’ \  
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOtMzQ2OGZhNjYwNWVmIn0.GuVau-3aTtYAZeQL0iJOBRif_Ir7DKuE4BKuK-DsCyA' \
--data '    {
    "timestamp": [
        "2023-11-19T12:00:00Z",
        "2023-11-20T23:59:59Z"
    ],
    "reportType": "targets"
    }'

Note: The API allows searches for a period of 90 days. The date range should not exceed 90 days in the past.

Sample Response:

rpc

Copy{
    "data": {
        "topTargets": [
            {
                "emailAddress": "sacjha@raptoretdautoe2e.onmicrosoft.com",
                "malicious": 258,
                "phishing": 127,
                "bec": 42,
                "scam": 129
            },
            {
                "emailAddress": "aanderson@raptoretdautoe2e.onmicrosoft.com",
                "malicious": 50,
                "phishing": 32,
                "bec": 0,
                "scam": 0
            }
        ]
    }
}

Top 10 Senders by threat

This reporting API enables you to identify the top 10 external sender addresses that sent the most threat messages over the past 90 days.

Available API endpoints are:

Americas API endpoint:

Code Snippet

Copyhttps://api.us.etd.cisco.com/v1/messages/report/top

Europe API endpoint:

Code Snippet

Copyhttps://api.de.etd.cisco.com/v1/messages/report/top

Australia API endpoint:

Code Snippet

Copyhttps://api.au.etd.cisco.com/v1/messages/report/top

India API endpoint:

Code Snippet

Copyhttps://api.in.etd.cisco.com/v1/messages/report/top

Sample request using CURL:

curl

Copy  curl --location 'https://api.de.etd.cisco.com/v1/messages/report/top' \
--header 'x-api-key: apikeyTest’ \  
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <Bearer Token>' \
--data '    {
    "timestamp": [
        "2024-01-19T12:00:00Z",
        "2023-01-20T23:59:59Z"
    ],
    "reportType": "threatSenders"
    }'

Note: The API allows searches for a period of 90 days. The date range should not exceed 90 days in the past.

Sample Response:

rpc

Copy{
    "data": {
        "topExternalThreatSenders": [
            {
                "emailAddress": "sacjha@raptoretdautoe2e.onmicrosoft.com",
                "total": 30
            },
            {
                "emailAddress": "aanderson@raptoretdautoe2e.onmicrosoft.com",
                "total": 50
            }
        ]
    }
}