Remediate messages request

Enqueues the message IDs provided in the request for remediation from the user's o365 inbox.

POST https://<etp_instance_addr>/api/v1/messages/remediate

Required headers:

Content-Type: application/json—Specifies that the server's response body is expected to be in JSON format.

x-fireeye-api-key: <key>—Specifies your personal API key.

Entitlement:

etp.email_trace.update and etp.email_trace.delete

Request body parameters

message_ids—(string) Required. List of Email Security - Cloud message IDs. Maximum: 300 message IDs.
Message IDs having a status in the list below are ignored.
["Deleted", "Dropped", "Dropped(OOB)", "Dropped (OOB Retroactive)", "Rejected", "Split", "Permanent Failure"]
action_override—(string) Optional. Allows you to override the default. Allowed values are "delete", "quarantine", and "move"
Note: "delete" is a permanent delete.
classification —(string) Optional. For Native mode domains, based on the prioritized verdict corresponding remediation action will be taken.
Priority for verdict type is "Malicious" > "Riskware" > "Virus" > "Spam".
Defaults to "Malicious"
Allowed values are "Spam", "Virus" and "Malicious", and "Riskware".
move_to—(string) Optional. When "move" is chosen for action_override, this parameter is mandatory and allows you to specify the folder to move to. Possible values ["junk email", "junkemail", "deleted items", "deleteditems", and <any folder>].
The values "junk email", "junkemail", "deleted items", and "deleteditems" will move an email to the o365 well-known folders Junk Email and Deleted Items, respectively. These values are not case sensitive.
<any folder> can be a custom folder in user"s mail box. If a folder does not exist, a new custom folder with that name will be created first before moving an email.

Request body examples:

For a move action override:

{
  "message_ids": ["23403224893D759D596005801"],
  "action_override": "move",
  "move_to": "test"
}

When action_override is "delete" or "quarantine" and the "move_to" folder is passed, "move_to" will be ignored:

{
  "message_ids":[
    "6D1004243EFDAA4D55b90d4f3",
    ...
  ],
  "action_override": "delete",
  "move_to":"Trash"
}

Remediate messages response

Values for ID and other fields are for illustration purposes only.

{
  "data": {
    "successful": [// list of message ids succesfully enqueued for remediation ],
    "failed": [// list of message ids which were not successfull ],
    "failure_reasons": [ // details of the failures. Message ids grouped by failure reason
      {
        "reason": "reason1",
        "message_ids": [
          "messageid1", "messageid2", ...
        ]
      },
      ...
    ]
  },
  "meta": {
    "copyright": "Copyright 2019 Fireeye Inc"
  }
}

Response examples:

Success:

{
  "data": {
    "successful": ["23403224893D759D596005801"],
  },
  "meta": {
    "copyright": "Copyright 2019 Fireeye Inc"
  }
}

Failure:

{
  "data": {
    "successful": [
      "3635323118193DAD55b90d4f3"
    ],
    "failed": [
      "B635323113293DAD55b90d4f3q"
    ],
    "failure_reasons": [
      {
        "reason": "Invalid etp_message_id(s) or insufficient privileges to remediate message(s)",
        "message_ids": [
          "B635323113293DAD55b90d4f3q"
        ]
      }
    ]
  },
  "meta": {
    "copyright": "Copyright 2019 Fireeye Inc"
  }
}

cURL code sample: remediate messages

curl -k https://<APIURI>/messages/remediate -H "x-fireeye-api-key: <APIKEY>" -d ' {"message_ids":["6D1004243EFDAA4D55b90d4f3", ...], "action_override": "delete"}

This cURL sample includes the following options:

-X POST—This option changes the HTTP method to POST.
-H 'x-fireeye-api-key: xxxxxxxxxxxxxxx'—This header specifies your personal API key.
https://<APIURI>/v1/messages/remediate—The email remediate request URL. Replace <APIURI> with the IP address of your Email Security — Cloud instance.
-d '<data>'—The request parameters.