Views:
Queries the results of actions on specified email messages or user accounts through Take actions on user accounts and Take actions on email messages APIs.

HTTPS Request

  • To query action results of user accounts:
    GET https://<serviceURL>/v1/mitigation/accounts
  • To query action results of email messages:
    GET https://<serviceURL>/v1/mitigation/mails

Request Parameters

Important
Important
The request must contain the required parameters.
Parameter
Description
Required Parameter
batch_id
Unique ID of a Threat Mitigation API request
To query actions taken within a single request, use this parameter.
start
end
Start and end time during which action results are to retrieve. Format: ISO 8601 timestamp to the second or millisecond in UTC, yyyy-mm-ddThh:mm:ss[.mmm]Z. For example, 2016-07-22T01:51:31Z or 2016-07-22T01:51:31.001Z.
The request retrieves logs within a maximum of 72 hours before the point of time when the request is sent according to the start and end settings:
  • If both start and end are not specified, the request retrieves logs within five minutes before the point of time when the request is sent.
  • If both start and end are specified, the request retrieves logs within the configured duration. Make sure the end time is no earlier than the start time.
  • If only start is specified, the request retrieves logs within five minutes after the point of the configured start time.
  • If only end is specified, the request retrieves logs within five minutes before the point of the configured end time.
Optional Parameter
limit
Number of action results to display at a time. A maximum of 500 are allowed
If not specified, the value is set to 500 by default.
If the total action results requested exceed the specified limit, a URL is provided in the next_link field in the response. Use this URL to form a second request to retrieve the remaining action results for the previous request. Repeat this until all action results for the first request are obtained.

Request Example

Example 1: retrieve the results of actions taken on user accounts within a single request
GET https://api.tmcas.trendmicro.com/v1/mitigation/accounts?batch_id=b97d5470-3bec-11e9-b842-158f7dd62a77
Authorization: Bearer 1de231142eef3f83928da98dc251fbebb6cafe77
Example 2: retrieve the results of actions taken on email messages from 2019-03-19 03:35:07.000 to 2019-03-19 05:47:07:000 (UTC), with the number of items to display at a time being 10
GET https://api.tmcas.trendmicro.com/v1/siem/mails?start=2019-03-19T03:35:07.000Z&end=2019-03-19T05:47:07.000Z&limit=10
Authorization: Bearer 1de231142eef3f83928da98dc251fbebb6cafe77

Response

On success, the service sends back an HTTP 200 response and returns a response body in JSON format; otherwise, the service sends back an error message in JSON format with error details. For more information about errors, see API responses.

Response Example

HTTP/1.1 200
Content-Type: application/json

{
  "count": 1,
  "current_link": "https://api.tmcas.trendmicro.com/v1/mitigation/accounts?batch_id=228ab860-46cc-11e9-8071-ff4462689877&limit=1",
  "next_link": "https://api.tmcas.trendmicro.com/v1/mitigation/accounts?batch_id=228ab860-46cc-11e9-8071-ff4462689877&limit=1&&offset=01",
  "actions": [
    {
           "action_type": "ACCOUNT_DISABLE",
           "service": "exchange",
           "account_provider": "office365",
           "account_user_email": "user@example.com",
           "action_id": "24e9de10-46cc-11e9-8071-ff4462689877",
           "batch_id": "228ab860-46cc-11e9-8071-ff4462689877",
           "status": "Success",
           "action_requested_at": "2019-03-04T06:30:21.613Z",
           "action_executed_at": "2019-03-04T06:30:21.613Z",
           "error_code": 0,
           "error_message": "success"
     }
  ]
}

Response Fields

The following table describes the available fields for the response body.
Note
Note
All time-related fields in the table are set to Coordinated Universal Time (UTC).
Field
Data Type
Description
count
Integer
Number of action results returned in the current response
current_link
String
URL in the current request
next_link
String
URL for the follow-up request if the requested action results exceed the specified limit to display at a time. Use this URL to form a second request to retrieve the remaining action results for the previous request. Repeat this until all action results for the first request are obtained.
actions
JSON array
Details of the requested action results
actions/action_type
String
Action taken on an email message or user account
actions/service
String
Name of the protected service to which the API applied
actions/account_provider
String
Provider of the protected service
actions/account_user_email
String
Email address used to create the user account on which an action was taken
actions/mailbox
String
Email address of an email message on which an action was taken
actions/mail_message_id
String
Internet message ID of an email message on which an action was taken
actions/mail_unique_id
String
Unique ID of an email message on which an action was taken
actions/action_id
String
Unique ID of a threat mitigation task
actions/batch_id
String
Unique ID of a Threat Mitigation API request
actions/status
String
Status of an action taken. Options include:
  • Created: The API request containing the action is received.
  • Executing: The action is being processed.
  • Success: The action is successfully taken.
  • Skipped: The action is skipped for certain reason. For example, the same action was requested twice.
  • Failed: The action fails.
actions/action_requested_at
ISO 8601 timestamp
Date and time when the API request containing the action was received
actions/action_executed_at
ISO 8601 timestamp
Date and time when the action was processed
actions/error_code
Integer
Result code of the action. Options include:
  • 0
  • 200
  • -100
  • -101
  • -102
  • -104
  • -999
  • -410
  • -411
  • -412
Note
Note
Error codes -410, -411, and -412 are applicable to Exchange Online only.
actions/error_message
String
String describing the result code. Options corresponding to each error code include:
  • 0: success
  • 200: The user is already disabled.
  • -100: The service account could not be found.
  • -101: The service account is not valid.
  • -102: The access token could not be found.
  • -104: Failed to connect to EWS.
  • -999: An unknown error has occurred.
  • -410: The email message could not be found.
  • -411: The email message is already quarantined.
  • -412: The email message is already deleted.