Takes actions on a batch of specified email messages, including deleting an email message, quarantining an email message, and restoring a quarantined email message.
HTTPS Request
POST https://<serviceURL>/v1/mitigation/mails
Request Parameters
The request must contain the required parameters.
|
Parameter |
Description |
|---|---|
|
Required Parameter |
|
|
action_type |
Action to take on an email message. Options include:
Note:
For Gmail, only MAIL_DELETE is supported.
Note:
The MAIL_RESTORE action is supported only for Exchange Online. Quarantined email messages can also be manually restored from the Quarantine screen on the Cloud App Security management console. |
|
service |
Name of the protected service to which the API applies. Options include:
|
|
account_provider |
Provider of the protected service. Options include:
|
|
mailbox |
Email address of an email message to take action on |
|
mail_message_id |
Internet message ID of an email message to take action on It can be obtained from the Sweep for email messages or Get Quarantine Events API of Cloud App Security or the Microsoft Graph API. To use this API properly, provide at least one of mail_message_id and mail_unique_id. Trend Micro recommends providing both in the request. Note:
This parameter is optional for Gmail. |
|
mail_unique_id |
Unique ID of an email message to take action on It can be obtained from the Sweep for email messages or Get Quarantine Events API of Cloud App Security or the Microsoft Graph API. To use this API properly, provide at least one of mail_message_id and mail_unique_id. Trend Micro recommends providing both in the request. |
|
mail_message_delivery_time |
Date and time when an email message to take action on is sent It can be obtained from the Sweep for email messages or Get Quarantine Events API of Cloud App Security or the Microsoft Graph API or EWS API. |
|
detection_time |
Date and time when the security event was detected It applies only to the MAIL_RESTORE action and can be obtained from the Cloud App Security Get Quarantine Events API. |
|
mail_log_id |
ID that uniquely identifies a log item It applies only to the MAIL_RESTORE action and can be obtained from the Cloud App Security Get Quarantine Events API. |
Request Example
POST https://api.tmcas.trendmicro.com/v1/mitigation/mails
Authorization: Bearer 1de231142eef3f83928da98dc251fbebb6cafe77
Content-Type: application/json
[
{
"action_type": "MAIL_DELETE",
"service": "gmail",
"account_provider": "google",
"mailbox": "user1@example1.com",
"mail_message_id": "<HK0PR06MB28364369C4D9F8255DBB229081410@HK0PR77MB2836.apcprd06.prod.example1.com>",
"mail_unique_id": "AAMkAGRhODQyZDAzLWNmNjEtNDY7OS1iOWM3LWVmODUxMDk4ZjE1ZgBGAAAAAAABcyFCsOdnTohKgA0TJdjUB
wAYbtU+cD0jRZmfu0kuMtvEAAAAAAEMAAAYbtU+cD0jRZmfu0kuMtvEAAF/JGRaAAA=",
"mail_message_delivery_time":"2019-03-15T07:44:27.000Z"
},
{
"action_type": "MAIL_QUARANTINE",
"service": "exchange",
"account_provider": "office365",
"mailbox": "user2@example2.com",
"mail_message_id": "<RK0PR06MB28364369C4D9F8255DBB779081410@HK0PR06MB2836.apcprd04.prod.example2.com>",
"mail_unique_id": "BAMkAGRhODQyZDAzLWNmNjEtNDY2OS1iOWM7LWVmODUxMDk4ZjE1ZgBGAAAAAAABcyFCsOdnTohKgA0TJdjUB
wAYbtU+cD0jRZmfu0kuMtvEAAAAAAEMAAAYbtU+cD0jRZmfu0kuMtvEAAF/JGRaAAA=",
"mail_message_delivery_time":"2019-03-15T07:45:27.000Z"
},
{
"action_type": "MAIL_RESTORE",
"service": "exchange",
"account_provider": "office365",
"mailbox": "user3@example3.onmicrosoft.com",
"detection_time": "2021-10-25T09:51:26.697Z",
"mail_unique_id": "AAkALgAAAAAAHYQDEapmEc2byACqAC-EWg0AJUMWJ_w_F0WJ1OxbHWzuuAABMEsyEwAA",
"mail_log_id": "1d9f27ea-3579-11ec-8159-00224809f763",
"mail_message_id": "<HK0PR02MB3698C584C7E6844016D0455C98839@HK0PR02MB3698.apcprd02.prod.example4.com>",
"mail_message_delivery_time": "2021-10-25T09:51:00.000Z"
}
]
HTTP Request Body
The request body is an array of email messages with detailed information about each one.
Response
On success, the service sends back an HTTP 201 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 201
Content-Type: application/json
{
"code": 0,
"msg": "",
"batch_id": "3fa85f64-5717-4562-b3fc-2c963f66af77"
"tracdId": "cabdfasdfdasfdsab-411f-a222-33ec6f44cc77"
}
Response Fields
The following table describes the available fields for the response body.
|
Field |
Data Type |
Description |
|---|---|---|
|
code |
Integer |
Result code of the request. For an HTTP 200 response, the value is fixed to 0 |
|
msg |
String |
String describing the result code. For an HTTP 200 response, the value is null |
|
batch_id |
String |
Unique ID of the API request, including all actions to take on email messages specified within this request You can use it to query the action results. For more information, see Query Action Results. |
|
traceId |
String |
Randomly generated identity to uniquely trace the request |