Edit

analyzedEmail: remediate

Namespace: microsoft.graph.security

Remove a potential threat from end users' mailboxes.

Remediation means to take prescribed action against a threat. This API can trigger email purge actions like move to junk, move to deleted items, soft delete, hard delete, or move to Inbox. This API enables scenarios and use cases such as SOAR integration, playbooks, and automations. For more information read email remediation, trigger action and track actions. If there is false positives admins can take move to inbox action.

Permissions

Choose the permission or permissions marked as least privileged for this API. Use a higher privileged permission or permissions only if your app requires it. For details about delegated and application permissions, see Permission types. To learn more about these permissions, see the permissions reference.

Permission type Least privileged permissions Higher privileged permissions
Delegated (work or school account) Not supported. Not supported.
Delegated (personal Microsoft account) Not supported. Not supported.
Application SecurityAnalyzedMessage.ReadWrite.All Not available.

HTTP request

POST /security/collaboration/analyzedEmails/remediate

Request headers

Name Description
Authorization Bearer {token}. Required. Learn more about authentication and authorization.
Content-Type application/json. Required.

Request body

In the request body, supply a JSON representation of the parameters.

The following table lists the parameters that are required when you call this action.

Parameter Type Description
displayName String The name of the remediation that is used as a reference in the action center.
description String The description of the remediation.
severity microsoft.graph.security.remediationSeverity The severity of the remediation. The possible values are: low, medium, high, unknownFutureValue.
action microsoft.graph.security.remediationAction The types of move and delete actions that are supported. The possible values are: moveToJunk, moveToInbox, hardDelete, softDelete, moveToDeletedItems, unknownFutureValue, moveToQuarantine. Use the Prefer: include-unknown-enum-members request header to get the following members from this evolvable enum: moveToQuarantine.
remediateSendersCopy Boolean For internal or outbound email, indicates whether to remediate the sender's copy of an email.
analyzedEmails microsoft.graph.security.analyzedEmail collection Contains the networkMessageId and recipientEmailAddress values of the analyzed emails.

Response

If successful, this action returns a 202 Accepted response code and a Location header with a link to the tracking information.

Note: The response to the action can be tracked in https://security.microsoft.com/action-center/history. To learn more, see Use the Action center.

Examples

Request

The following example shows a request.

POST https://graph.microsoft.com/v1.0/security/collaboration/analyzedEmails/remediate
Content-Type: application/json

{
    "displayName": "Clean up Phish email",
    "description": "Delete email",
    "severity": "medium",
    "action": "softDelete",
    "remediateSendersCopy": "false",
    "analyzedEmails": [
      {
        "networkMessageId": "73ca4154-58d8-43d0-a890-08dc18c52e6d",
        "recipientEmailAddress": "hannah.jarvis@contoso.com"
      },
      {
        "networkMessageId": "73ca4154-58d8-43d0-a890-08dc18c52e6d",
        "recipientEmailAddress": "preston.morales@contoso.com"
      }
    ]
}

Response

The following example shows the response.

Note: The response object shown here might be shortened for readability.

HTTP/1.1 202 Accepted
Location: https://security.microsoft.com/action-center/history?filters={"bulkId":["{bulkId}"]}&tid={tid}
Content-Type: application/json;text/plain
Content-Length: 0
  • Last updated on