Commands › Exchange Online

New-ProtectionAlert

Exchange Online ExchangeOnlineManagement New-*

For more information, see Security & Compliance PowerShell. Use the New-ProtectionAlert cmdlet to create alert policies in the Microsoft Purview compliance portal and the Microsoft Defender portal. Alert policies contain conditions that define the user activities to monitor, and the notification options for email alerts and entries. > [!NOTE] > Although the cmdlet is available, you receive the following error if you don't have an enterprise license: > > _Creating advanced alert policies requires an Office 365 E5 subscription or Office 365 E3 subscription with an Office 365 Threat Intelligence

Quick start script

# New-ProtectionAlert — quick start (serv365.ai)
# 1. Connect (app-only shown; interactive: omit the certificate parameters)
Connect-ExchangeOnline -CertificateThumbprint $thumb -AppId $appId -Organization $org

# 2. Capture the current state first — you cannot roll back what you never recorded
$before = Get-ProtectionAlert
$before | Format-List

# 3. Make the change (dry run first)
New-ProtectionAlert -Category <AlertRuleCategory> -Name <String> -NotifyUser <MultiValuedProperty> -WhatIf
New-ProtectionAlert -Category <AlertRuleCategory> -Name <String> -NotifyUser <MultiValuedProperty>

# 4. Verify and diff
$after = Get-ProtectionAlert
Compare-Object ($before | Out-String) ($after | Out-String)

Syntax

New-ProtectionAlert -Category <AlertRuleCategory> -Name <String> -NotifyUser <MultiValuedProperty> -ThreatType <ThreatAlertType>
 [-AggregationType <AlertAggregationType>]
 [-AlertBy <MultiValuedProperty>]
 [-AlertFor <MultiValuedProperty>]
 [-Comment <String>]
 [-Confirm]
 [-CorrelationPolicyId <System.Guid>]
 [-Description <String>]
 [-Disabled <Boolean>]
 [-Filter <String>]
 [-LogicalOperationName <String>]
 [-NotificationCulture <CultureInfo>]
 [-NotificationEnabled <Boolean>]
 [-NotifyUserOnFilterMatch <Boolean>]
 [-NotifyUserSuppressionExpiryDate <DateTime>]
 [-NotifyUserThrottleThreshold <Int32>]
 [-NotifyUserThrottleWindow <Int32>]
 [-Operation <MultiValuedProperty>]
 [-PrivacyManagementScopedSensitiveInformationTypes <MultiValuedProperty>]
 [-PrivacyManagementScopedSensitiveInformationTypesForCounting <MultiValuedProperty>]
 [-PrivacyManagementScopedSensitiveInformationTypesThreshold <System.UInt64>]
 [-CustomProperties <PswsHashtable>]
 [-Severity <RuleSeverity>]
 [-Threshold <Int32>]
 [-TimeWindow <Int32>]
 [-UseCreatedDateTime <System.Boolean>]
 [-VolumeThreshold <System.UInt64>]
 [-WhatIf]
 [<CommonParameters>]

Parameters (31)

Parameter	Type	Required	What it controls
-Category	AlertRuleCategory	yes	The Category parameter specifies a category for the alert policy. Valid values are:
-Name	String	yes	The Name parameter specifies the unique name for the alert policy. If the value contains spaces, enclose the value in quotation marks (").
-NotifyUser	MultiValuedProperty	yes	The NotifyUser parameter specifies the SMTP address of the user who receives notification messages for the alert policy. You can specify multiple values separated by commas.
-ThreatType	ThreatAlertType	yes	The ThreatType parameter specifies the type of activities that are monitored by the alert policy. Valid values are:
-AggregationType	AlertAggregationType		The AggregationType parameter specifies the how the alert policy triggers alerts for multiple occurrences of monitored activity. Valid values are:
-AlertBy	MultiValuedProperty		The AlertBy parameter specifies the scope for aggregated alert policies. Valid values are determined by the ThreatType parameter value:
-AlertFor	MultiValuedProperty		This parameter is reserved for internal Microsoft use.
-Comment	String		The Comment parameter specifies an optional comment. If you specify a value that contains spaces, enclose the value in quotation marks ("), for example: "This is an admin note".
-Confirm	SwitchParameter		The Confirm switch specifies whether to show or hide the confirmation prompt. How this switch affects the cmdlet depends on whether the cmdlet requires confirmation before proceeding.
-CorrelationPolicyId	Guid		{{ Fill CorrelationPolicyId Description }}
-CustomProperties	PswsHashtable		{{ Fill CustomProperties Description }}
-Description	String		The Description parameter specifies descriptive text for the alert policy. If the value contains spaces, enclose the value in quotation marks (").
-Disabled	Boolean		The Disabled parameter enables or disables the alert policy. Valid values are:
-Filter	String		The Filter parameter uses OPATH syntax to filter the results by the specified properties and values. The search criteria uses the syntax `"Property -ComparisonOperator 'Value'"`.
-LogicalOperationName	String		{{ Fill LogicalOperationName Description }}
-NotificationCulture	CultureInfo		The NotificationCulture parameter specifies the language or locale that's used for notifications.
-NotificationEnabled	Boolean		{{ Fill NotificationEnabled Description }}
-NotifyUserOnFilterMatch	Boolean		The NotifyUserOnFilterMatch parameter specifies whether to trigger an alert for a single event when the alert policy is configured for aggregated activity. Valid values are:
-NotifyUserSuppressionExpiryDate	DateTime		The NotifyUserSuppressionExpiryDate parameter specifies whether to temporarily suspend notifications for the alert policy. Until the specified date-time, no notifications are sent for detected activities.
-NotifyUserThrottleThreshold	Int32		The NotifyUserThrottleThreshold parameter specifies the maximum number of notifications for the alert policy within the time period specified by the NotifyUserThrottleWindow parameter. Once the maximum number of...
-NotifyUserThrottleWindow	Int32		The NotifyUserThrottleWindow parameter specifies the time interval in minutes that's used by the NotifyUserThrottleThreshold parameter. Valid values are:
-Operation	MultiValuedProperty		The Operation parameter specifies the activities that are monitored by the alert policy. For the list of available activities, see the Audited activities tab at [Audited...
-PrivacyManagementScopedSensitiveInformationTypes	MultiValuedProperty		{{ Fill PrivacyManagementScopedSensitiveInformationTypes Description }}
-PrivacyManagementScopedSensitiveInformationTypesForCounting	MultiValuedProperty		{{ Fill PrivacyManagementScopedSensitiveInformationTypesForCounting Description }}
-PrivacyManagementScopedSensitiveInformationTypesThreshold	UInt64		{{ Fill PrivacyManagementScopedSensitiveInformationTypesThreshold Description }}
-Severity	RuleSeverity		The Severity parameter specifies the severity of the detection. Valid values are:
-Threshold	Int32		The Threshold parameter specifies the number of detections that must be exceeded within the time period defined by the TimeWindow parameter to trigger the alert policy. A valid value is an integer that's greater than...
-TimeWindow	Int32		The TimeWindow parameter specifies the time interval in minutes for number of detections specified by the Threshold parameter. A valid value is an integer that's greater than 60 (one hour).
-UseCreatedDateTime	Boolean		{{ Fill UseCreatedDateTime Description }}
-VolumeThreshold	UInt64		{{ Fill VolumeThreshold Description }}
-WhatIf	SwitchParameter		The WhatIf switch doesn't work in Security & Compliance PowerShell.

Reference facts derived from Microsoft documentation, © Microsoft, licensed CC BY 4.0; restructured with original guidance by serv365.ai.