Merge pull request #23304 from microsoftgraph/aspati/mdoanalyzedemail…

…sapi-docs Documentation for security-collaborationroot-analyzedemails
microsoftgraph · Mar 8, 2024 · 73273b5 · 73273b5
2 parents ee2676c + 192bda2
commit 73273b5
Show file tree

Hide file tree

Showing 23 changed files with 1,454 additions and 3 deletions.
diff --git a/api-reference/beta/api/security-analyzedemail-get.md b/api-reference/beta/api/security-analyzedemail-get.md
@@ -0,0 +1,150 @@
+---
+title: "Get analyzedEmail"
+description: "Read the properties and relationships of an analyzedEmail object."
+author: "malvika-balaraj"
+ms.localizationpriority: medium
+ms.prod: "security"
+doc_type: apiPageType
+---
+
+# Get analyzedEmail
+
+Namespace: microsoft.graph.security
+
+[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)]
+
+Read the properties and relationships of an [analyzedEmail](../resources/security-analyzedemail.md) object.
+
+## 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](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference).
+
+<!-- {
+  "blockType": "permissions",
+  "name": "security-analyzedemail-get-permissions"
+}
+-->
+[!INCLUDE [permissions-table](../includes/permissions/security-analyzedemail-get-permissions.md)]
+
+## HTTP request
+
+<!-- {
+  "blockType": "ignored"
+}
+-->
+``` http
+GET /security/collaboration/analyzedEmails/{analyzedEmailId}
+```
+
+
+## Request headers
+
+|Name|Description|
+|:---|:---|
+|Authorization|Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts).|
+
+## Request body
+
+Don't supply a request body for this method.
+
+## Response
+
+If successful, this method returns a `200 OK` response code and a [microsoft.graph.security.analyzedEmail](../resources/security-analyzedemail.md) object in the response body.
+
+## Examples
+
+### Request
+
+The following example shows a request.
+<!-- {
+  "blockType": "request",
+  "name": "get_analyzedemail"
+}
+-->
+``` http
+GET https://graph.microsoft.com/beta/security/collaboration/analyzedEmails/{analyzedEmailId}
+```
+
+
+### Response
+
+The following example shows the response.
+>**Note:** The response object shown here might be shortened for readability.
+<!-- {
+  "blockType": "response",
+  "truncated": true,
+  "@odata.type": "microsoft.graph.security.analyzedEmail"
+}
+-->
+``` http
+HTTP/1.1 200 OK
+Content-Type: application/json
+
+{
+  "value": {
+    "@odata.type": "#microsoft.graph.security.analyzedEmail",
+    "id": "3570a93a-82b1-ffb9-8c26-a9a2ca002a17",
+    "loggedDateTime": "String (timestamp)",
+    "networkMessageId": "String",
+    "internetMessageId": "String",
+    "senderDetail": {
+      "@odata.type": "microsoft.graph.security.analyzedEmailSenderDetail"
+    },
+    "recipientEmailAddresses": [
+      "String"
+    ],
+    "distributionList": "String",
+    "subject": "String",
+    "returnPath": "String",
+    "directionality": "String",
+    "originalDelivery": {
+      "@odata.type": "microsoft.graph.security.analyzedEmailDeliveryDetail"
+    },
+    "latestDelivery": {
+      "@odata.type": "microsoft.graph.security.analyzedEmailDeliveryDetail"
+    },
+    "attachmentsCount": "Integer",
+    "attachments": [
+      {
+        "@odata.type": "microsoft.graph.security.analyzedEmailAttachment"
+      }
+    ],
+    "urlsCount": "Integer",
+    "urls": [
+      {
+        "@odata.type": "microsoft.graph.security.analyzedEmailUrl"
+      }
+    ],
+    "language": "String",
+    "sizeInBytes": "Integer",
+    "alertIds": [
+      "String"
+    ],
+    "exchangeTransportRules": [
+      {
+        "@odata.type": "microsoft.graph.security.analyzedEmailExchangeTransportRuleInfo"
+      }
+    ],
+    "overrideSources": [
+      "String"
+    ],
+    "threatType": "String",
+    "detectionMethods": [
+      "String"
+    ],
+    "contexts": [
+      "String"
+    ],
+    "authenticationDetails": {
+      "@odata.type": "microsoft.graph.security.analyzedEmailAuthenticationDetail"
+    },
+    "phishConfidenceLevel": "String",
+    "spamConfidenceLevel": "String",
+    "bulkComplaintLevel": "String",
+    "emailClusterId": "String",
+    "policyAction": "String",
+    "policy": "String"
+  }
+}
+```
+
diff --git a/api-reference/beta/api/security-analyzedemail-remediate.md b/api-reference/beta/api/security-analyzedemail-remediate.md
@@ -0,0 +1,120 @@
+---
+title: "analyzedEmail: remediate "
+description: "Remove a potential threat from end users' mailboxes."
+author: MishraSoumyaMS
+ms.localizationpriority: medium
+ms.prod: security
+doc_type: apiPageType
+---
+
+# analyzedEmail: remediate
+
+Namespace: microsoft.graph.security
+
+[!INCLUDE [beta-disclaimer](../../includes/beta-disclaimer.md)]
+
+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](/microsoft-365/security/office-365-security/remediate-malicious-email-delivered-office-365?view=o365-worldwide&preserve-view=true). 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](/graph/permissions-overview#best-practices-for-using-microsoft-graph-permissions). For details about delegated and application permissions, see [Permission types](/graph/permissions-overview#permission-types). To learn more about these permissions, see the [permissions reference](/graph/permissions-reference).
+
+<!-- {
+  "blockType": "permissions",
+  "name": "security-analyzedemail-remediate-permissions"
+}
+-->
+[!INCLUDE [permissions-table](../includes/permissions/security-analyzedemail-remediate-permissions.md)]
+
+## HTTP request
+
+<!-- {
+  "blockType": "ignored"
+}
+-->
+``` http
+POST /security/collaboration/analyzedEmails/remediate
+```
+
+## Request headers
+
+|Name|Description|
+|:---|:---|
+|Authorization|Bearer {token}. Required. Learn more about [authentication and authorization](/graph/auth/auth-concepts).|
+|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`.|
+|approverUpn|String| Tracks who approved the action. |
+|remediateSendersCopy|Boolean| For internal or outbound email, indicates whether to remediate the sender's copy of an email. |
+|analyzedEmails|[microsoft.graph.security.analyzedEmail](../resources/security-analyzedemail.md) collection|The unique ID of the analyzed email. The ID can be found from the analyzedemails, analyzedemails/Id or runHuntingQuery/reportId.
+
+## 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](/microsoft-365/security/defender/m365d-action-center?view=o365-worldwide&preserve-view=true).
+
+## Examples
+
+### Request
+
+The following example shows a request.
+<!-- {
+  "blockType": "request",
+  "name": "analyzedemailthis.remediate"
+}
+-->
+``` http
+POST https://graph.microsoft.com/beta/security/collaboration/analyzedEmails/remediate
+Content-Type: application/json
+
+{
+    "displayName": "Clean up Phish email",
+    "description": "Delete email",
+    "severity": "medium",
+    "action": "softDelete",
+    "remediateSendersCopy": "false",
+     "analyzedEmails": [
+        {
+            "id": "73ca4154-58d8-43d0-a890-08dc18c52e6d-1311265001240363512-1"
+        },
+        {
+            "id": "73ca4154-58d8-43d0-a890-08dc18c52e6d-13805748846361900678-1"
+        }
+    ]
+}
+```
+
+
+### Response
+
+The following example shows the response.
+>**Note:** The response object shown here might be shortened for readability.
+<!-- {
+  "blockType": "response",
+  "truncated": true
+}
+-->
+``` http
+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
+```
+
+
+
+