Commands › Exchange Online
New-InboxRule
Create Inbox rules in mailboxes. Inbox rules process messages in the Inbox based on conditions and take actions such as moving a message to a specified folder or deleting a message. You must have adequate permissions on the mailbox to create an Inbox rule.
Quick start script
# New-InboxRule — 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-InboxRule
$before | Format-List
# 3. Make the change (dry run first)
New-InboxRule -Name <String> -FromMessageId <MailboxStoreObjectIdParameter> -ValidateOnly <SwitchParameter> -WhatIf
New-InboxRule -Name <String> -FromMessageId <MailboxStoreObjectIdParameter> -ValidateOnly <SwitchParameter>
# 4. Verify and diff
$after = Get-InboxRule
Compare-Object ($before | Out-String) ($after | Out-String)Syntax — 2 parameter sets
Identity
New-InboxRule [-Name] <String>
[-AlwaysDeleteOutlookRulesBlob]
[-AnyCategory <Boolean>]
[-AssignedCategories <String[]>]
[-ApplyCategory <MultiValuedProperty>]
[-ApplySystemCategory <MultiValuedProperty>]
[-BodyContainsWords <MultiValuedProperty>]
[-BulkCategory <Boolean>]
[-ClearCategories <Boolean>]
[-ClearFlag <Boolean>]
[-CompleteFlag <Boolean>]
[-Confirm]
[-CopyToFolder <MailboxFolderIdParameter>]
[-DeleteMessage <Boolean>]
[-DeleteSystemCategory <MultiValuedProperty>]
[-DisplayAlert <String>]
[-DomainController <Fqdn>]
[-ExceptIfAnyCategory <Boolean>]
[-ExceptIfAssignedCategories <String[]>]
[-ExceptIfBulkCategory <Boolean>]
[-ExceptIfBodyContainsWords <MultiValuedProperty>]
[-ExceptIfFlaggedForAction <String>]
[-ExceptIfFrom <RecipientIdParameter[]>]
[-ExceptIfFromAddressContainsWords <MultiValuedProperty>]
[-ExceptIfHasAttachment <Boolean>]
[-ExceptIfHasClassification <MessageClassificationIdParameter[]>]
[-ExceptIfHeaderContainsWords <MultiValuedProperty>]
[-ExceptIfMessageTypeMatches <InboxRuleMessageType>]
[-ExceptIfMyNameInCcBox <Boolean>]
[-ExceptIfMyNameInToBox <Boolean>]
[-ExceptIfMyNameInToOrCcBox <Boolean>]
[-ExceptIfMyNameNotInToBox <Boolean>]
[-ExceptIfReceivedAfterDate <ExDateTime>]
[-ExceptIfReceivedBeforeDate <ExDateTime>]
[-ExceptIfRecipientAddressContainsWords <MultiValuedProperty>]
[-ExceptIfSentOnlyToMe <Boolean>]
[-ExceptIfSentTo <RecipientIdParameter[]>]
[-ExceptIfSubjectContainsWords <MultiValuedProperty>]
[-ExceptIfSubjectOrBodyContainsWords <MultiValuedProperty>]
[-ExceptIfWithImportance <Importance>]
[-ExceptIfWithinSizeRangeMaximum <ByteQuantifiedSize>]
[-ExceptIfWithinSizeRangeMinimum <ByteQuantifiedSize>]
[-ExceptIfWithSensitivity <Sensitivity>]
[-FlaggedForAction <String>]
[-FlagMessage <String>]
[-Force]
[-ForwardAsAttachmentTo <RecipientIdParameter[]>]
[-ForwardTo <RecipientIdParameter[]>]
[-From <RecipientIdParameter[]>]
[-FromAddressContainsWords <MultiValuedProperty>]
[-HasAttachment <Boolean>]
[-HasClassification <MessageClassificationIdParameter[]>]
[-HeaderContainsWords <MultiValuedProperty>]
[-Mailbox <MailboxIdParameter>]
[-MarkAsRead <Boolean>]
[-MarkImportance <Importance>]
[-MessageTypeMatches <InboxRuleMessageType>]
[-MoveToFolder <MailboxFolderIdParameter>]
[-MyNameInCcBox <Boolean>]
[-MyNameInToBox <Boolean>]
[-MyNameInToOrCcBox <Boolean>]
[-MyNameNotInToBox <Boolean>]
[-PermanentDelete <Boolean>]
[-PinMessage <Boolean>]
[-PlaySound <String>]
[-Priority <Int32>]
[-ReceivedAfterDate <ExDateTime>]
[-ReceivedBeforeDate <ExDateTime>]
[-RecipientAddressContainsWords <MultiValuedProperty>]
[-RedirectTo <RecipientIdParameter[]>]
[-SendTextMessageNotificationTo <MultiValuedProperty>]
[-SentOnlyToMe <Boolean>]
[-SentTo <RecipientIdParameter[]>]
[-SoftDeleteMessage <Boolean>]
[-StopProcessingRules <Boolean>]
[-SubjectContainsWords <MultiValuedProperty>]
[-SubjectOrBodyContainsWords <MultiValuedProperty>]
[-WhatIf]
[-WithImportance <Importance>]
[-WithinSizeRangeMaximum <ByteQuantifiedSize>]
[-WithinSizeRangeMinimum <ByteQuantifiedSize>]
[-WithSensitivity <Sensitivity>]
[<CommonParameters>]FromMessage
New-InboxRule -FromMessageId <MailboxStoreObjectIdParameter>
[-ValidateOnly]
[-AlwaysDeleteOutlookRulesBlob]
[-Confirm]
[-DomainController <Fqdn>]
[-ExceptIfFromSubscription <AggregationSubscriptionIdentity[]>]
[-Force]
[-FromSubscription <AggregationSubscriptionIdentity[]>]
[-Mailbox <MailboxIdParameter>]
[-WhatIf]
[<CommonParameters>]Parameters (84)
| Parameter | Type | Required | What it controls |
|---|---|---|---|
| -Name | String | yes | The Name parameter specifies the name of the Inbox rule. The maximum length is 512 characters. If the value contains spaces, enclose the value in quotation marks ("). |
| -FromMessageId | MailboxStoreObjectIdParameter | yes | The FromMessageId parameter specifies the message that's used to create the Inbox rule. The rule is based on the properties of the message. You identify the message by its Base64-encoded StoreObjectId property value.... |
| -ValidateOnly | SwitchParameter | yes | The ValidateOnly switch specifies whether to evaluate the potential success or failure of the command without making changes. You don't need to specify a value with this switch. |
| -AlwaysDeleteOutlookRulesBlob | SwitchParameter | The AlwaysDeleteOutlookRulesBlob switch hides a warning message when you use Outlook on the web (formerly known as Outlook Web App) or Exchange PowerShell to modify Inbox rules. You don't need to specify a value with... | |
| -AnyCategory | Boolean | This parameter is available only in the cloud-based service. | |
| -AssignedCategories | String[] | This parameter is available only in the cloud-based service. | |
| -ApplyCategory | MultiValuedProperty | The ApplyCategory parameter specifies an action for the Inbox rule that applies the specified category to messages. A valid value is any text value that you want to define as a category. You can specify multiple... | |
| -ApplySystemCategory | MultiValuedProperty | The ApplySystemCategory parameter specifies an action for the Inbox rule that applies the specified system category to messages. System categories are available to all mailboxes in the organization. Valid values are: | |
| -BodyContainsWords | MultiValuedProperty | The BodyContainsWords parameter specifies a condition for the Inbox rule that looks for the specified words or phrases in the body of messages. | |
| -BulkCategory | Boolean | This parameter is available only in the cloud-based service. | |
| -ClearCategories | Boolean | This parameter is available only in the cloud-based service. | |
| -ClearFlag | Boolean | This parameter is available only in the cloud-based service. | |
| -CompleteFlag | Boolean | This parameter is available only in the cloud-based service. | |
| -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. | |
| -CopyToFolder | MailboxFolderIdParameter | The CopyToFolder parameter specifies an action for the Inbox rule that copies messages to the specified mailbox folder. The syntax is `MailboxID:\ParentFolder[\SubFolder]`. | |
| -DeleteMessage | Boolean | The DeleteMessage parameter specifies an action for the Inbox rule that sends messages to the Deleted Items folder. Valid values are: | |
| -DeleteSystemCategory | MultiValuedProperty | The DeleteSystemCategory parameter specifies an action for the Inbox rule that deletes the specified system category from messages. System categories are available to all mailboxes in the organization. Valid values are: | |
| -DisplayAlert | String | This parameter is available only in the cloud-based service. | |
| -DomainController | Fqdn | This parameter is available only in on-premises Exchange. | |
| -ExceptIfAnyCategory | Boolean | This parameter is available only in the cloud-based service. | |
| -ExceptIfAssignedCategories | String[] | This parameter is available only in the cloud-based service. | |
| -ExceptIfBulkCategory | Boolean | This parameter is available only in the cloud-based service. | |
| -ExceptIfBodyContainsWords | MultiValuedProperty | The ExceptIfBodyContainsWords parameter specifies an exception for the Inbox rule that looks for the specified words or phrases in the body of messages. | |
| -ExceptIfFlaggedForAction | String | The ExceptIfFlaggedForAction parameter specifies an exception for the Inbox rule that looks messages with the specified message flag. Valid values are: | |
| -ExceptIfFrom | RecipientIdParameter[] | The ExceptIfFrom parameter specifies an exception for the Inbox rule that looks for the specified sender in messages. You can use any value that uniquely identifies the sender. For example: | |
| -ExceptIfFromAddressContainsWords | MultiValuedProperty | The ExceptIfFromAddressContainsWords parameter specifies an exception for the Inbox rule that looks for messages where the specified words are in the sender's email address. | |
| -ExceptIfHasAttachment | Boolean | The ExceptIfHasAttachment parameter specifies an exception for the Inbox rule that looks for messages with attachments. Valid values are: | |
| -ExceptIfHasClassification | MessageClassificationIdParameter[] | The ExceptIfHasClassification parameter specifies an exception for the Inbox rule that looks for messages with the specified message classification. You can find message classifications by using the... | |
| -ExceptIfHeaderContainsWords | MultiValuedProperty | The HeaderContainsWords parameter specifies an exception for the Inbox rule that looks for the specified words or phrases in the header fields of messages. | |
| -ExceptIfMessageTypeMatches | InboxRuleMessageType | The ExceptIfMessageTypeMatches parameter specifies an exception for the Inbox rule that looks for messages of the specified type. Valid values are: | |
| -ExceptIfMyNameInCcBox | Boolean | The ExceptIfMyNameInCcBox parameter specifies an exception for the Inbox rule that looks for messages where the mailbox owner is in the Cc field. Valid values are: | |
| -ExceptIfMyNameInToBox | Boolean | The ExceptIfMyNameInToBox parameter specifies an exception for the Inbox rule that looks for messages where the mailbox owner is in the To field. Valid values are: | |
| -ExceptIfMyNameInToOrCcBox | Boolean | The ExceptIfMyNameInToOrCcBox parameter specifies an exception for the Inbox rule that looks for messages where the mailbox owner is in the To or Cc fields Valid values are. | |
| -ExceptIfMyNameNotInToBox | Boolean | The ExceptIfMyNameNotInToBox parameter specifies an exception for the Inbox rule that looks for messages where the mailbox owner isn't in the To field. Valid values are: | |
| -ExceptIfReceivedAfterDate | ExDateTime | The ExceptIfReceivedAfterDate parameter specifies an exception for the Inbox rule that looks for messages received after the specified date. | |
| -ExceptIfReceivedBeforeDate | ExDateTime | The ExceptIfReceivedBeforeDate parameter specifies an exception for the Inbox rule that looks for messages received before the specified date. | |
| -ExceptIfRecipientAddressContainsWords | MultiValuedProperty | The ExceptIfRecipientAddressContainsWords parameter specifies an exception for the Inbox rule that looks for messages where the specified words are in recipient email addresses. | |
| -ExceptIfSentOnlyToMe | Boolean | The ExceptIfSentOnlyToMe parameter specifies an exception for the Inbox rule that looks for messages where the only recipient is the mailbox owner. Valid values are: | |
| -ExceptIfSentTo | RecipientIdParameter[] | The ExceptIfSentTo parameter specifies an exception that looks for recipients in messages. You can use any value that uniquely identifies the recipient. For example: | |
| -ExceptIfSubjectContainsWords | MultiValuedProperty | The ExceptIfSubjectContainsWords parameter specifies an exception for the Inbox rule that looks for the specified words or phrases in the Subject field of messages. | |
| -ExceptIfSubjectOrBodyContainsWords | MultiValuedProperty | The ExceptIfSubjectOrBodyContainsWords parameter specifies an exception for the Inbox rule that looks for the specified words or phrases in the Subject field or body of messages. | |
| -ExceptIfWithImportance | Importance | The ExceptIfWithImportance parameter specifies an exception for the Inbox rule that looks for messages with the specified importance level. Valid values are: | |
| -ExceptIfWithinSizeRangeMaximum | ByteQuantifiedSize | The ExceptIfWithinSizeRangeMaximum parameter specifies part of an exception for the Inbox rule that looks for messages that smaller than specified maximum size. | |
| -ExceptIfWithinSizeRangeMinimum | ByteQuantifiedSize | The ExceptIfWithinSizeRangeMinimum parameter specifies part of an exception for the Inbox rule that looks for messages that are larger than the specified minimum size. | |
| -ExceptIfWithSensitivity | Sensitivity | The ExceptIfWithSensitivity parameter specifies an exception for the Inbox rule that looks for messages with the specified sensitivity level. Valid values are: | |
| -FlaggedForAction | String | The FlaggedForAction parameter specifies a condition for the Inbox rule that looks for messages with the specified message flag. Valid values are: | |
| -FlagMessage | String | This parameter is available only in the cloud-based service. | |
| -Force | SwitchParameter | The Force switch hides warning or confirmation messages. You don't need to specify a value with this switch. | |
| -ForwardAsAttachmentTo | RecipientIdParameter[] | The ForwardAsAttachmentTo parameter specifies an action for the Inbox rule that forwards the message to the specified recipient as an attachment. You can use any value that uniquely identifies the recipient. For example: | |
| -ForwardTo | RecipientIdParameter[] | The ForwardTo parameter specifies an action for the Inbox rule that forwards the message to the specified recipient. You can use any value that uniquely identifies the recipient. For example: | |
| -From | RecipientIdParameter[] | The From parameter specifies a condition for the Inbox rule that looks for the specified sender in messages. You can use any value that uniquely identifies the sender. For example: | |
| -FromAddressContainsWords | MultiValuedProperty | The FromAddressContainsWords parameter specifies a condition for the Inbox rule that looks for messages where the specified words are in the sender's email address. | |
| -HasAttachment | Boolean | The HasAttachment parameter specifies a condition for the Inbox rule that looks for messages with attachments. Valid values are: | |
| -HasClassification | MessageClassificationIdParameter[] | The HasClassification parameter specifies a condition for the Inbox rule that looks for messages with the specified message classification. You can find message classifications by using the Get-MessageClassification... | |
| -HeaderContainsWords | MultiValuedProperty | The HeaderContainsWords parameter specifies a condition for the Inbox rule that looks for the specified words or phrases in the header fields of messages. | |
| -Mailbox | MailboxIdParameter | The Mailbox parameter specifies the mailbox that contains the Inbox rule. You can use any value that uniquely identifies the mailbox. For example: | |
| -MarkAsRead | Boolean | The MarkAsRead parameter specifies an action for the Inbox rule that marks messages as read. Valid values are: | |
| -MarkImportance | Importance | The MarkImportance parameter specifies an action for the Inbox rule that marks messages with the specified importance flag. Valid values are: | |
| -MessageTypeMatches | InboxRuleMessageType | The MessageTypeMatches parameter specifies a condition for the Inbox rule that looks for messages of the specified type. Valid values are: | |
| -MoveToFolder | MailboxFolderIdParameter | The MoveToFolder parameter specifies an action for the Inbox rule that moves messages to the specified mailbox folder. The syntax is `MailboxID:\ParentFolder[\SubFolder]`. | |
| -MyNameInCcBox | Boolean | The MyNameInCcBox parameter specifies a condition for the Inbox rule that looks for messages where the mailbox owner is in the Cc field. Valid values are: | |
| -MyNameInToBox | Boolean | The MyNameInToBox parameter specifies a condition for the Inbox rule that looks for messages where the mailbox owner is in the To field. Valid values are: | |
| -MyNameInToOrCcBox | Boolean | The MyNameInToOrCcBox parameter specifies a condition for the Inbox rule that looks for messages where the mailbox owner is in the To or Cc fields Valid values are. | |
| -MyNameNotInToBox | Boolean | The MyNameNotInToBox parameter specifies a condition for the Inbox rule that looks for messages where the mailbox owner isn't in the To field. Valid values are: | |
| -PermanentDelete | Boolean | This parameter is available only in the cloud-based service. | |
| -PinMessage | Boolean | The PinMessage parameter specifies an action for the Inbox rule that pins messages to the top of the Inbox. Valid values are: | |
| -PlaySound | String | This parameter is available only in the cloud-based service. | |
| -Priority | Int32 | The Priority parameter specifies a priority for the Inbox rule that determines the order of rule processing. A lower integer value indicates a higher priority, | |
| -ReceivedAfterDate | ExDateTime | The ReceivedAfterDate parameter specifies a condition for the Inbox rule that looks for messages received after the specified date. | |
| -ReceivedBeforeDate | ExDateTime | The ReceivedBeforeDate parameter specifies a condition for the Inbox rule that looks for messages received before the specified date. | |
| -RecipientAddressContainsWords | MultiValuedProperty | The RecipientAddressContainsWords parameter specifies a condition for the Inbox rule that looks for messages where the specified words are in recipient email addresses. | |
| -RedirectTo | RecipientIdParameter[] | The RedirectTo parameter specifies an action for the Inbox rule that redirects the message to the specified recipient. You can use any value that uniquely identifies the recipient. For example: | |
| -SendTextMessageNotificationTo | MultiValuedProperty | This parameter is available only in on-premises Exchange. | |
| -SentOnlyToMe | Boolean | The SentOnlyToMe parameter specifies a condition for the Inbox rule that looks for messages where the only recipient is the mailbox owner. Valid values are: | |
| -SentTo | RecipientIdParameter[] | The SentTo parameter specifies a condition for the Inbox rule that looks for messages with the specified recipients. You can use any value that uniquely identifies the recipient. For example: | |
| -SoftDeleteMessage | Boolean | This parameter is available only in the cloud-based service. | |
| -StopProcessingRules | Boolean | The StopProcessingRules parameter specifies an action for the Inbox rule that stops processing additional rules if the conditions of this Inbox rule are met. Valid values are:If set to $true, the StopProcessingRules... | |
| -SubjectContainsWords | MultiValuedProperty | The SubjectContainsWords parameter specifies a condition for the Inbox rule that looks for the specified words or phrases in the Subject field of messages. | |
| -SubjectOrBodyContainsWords | MultiValuedProperty | The SubjectOrBodyContainsWords parameter specifies a condition for the Inbox rule that looks for the specified words or phrases in the Subject field or body of messages. | |
| -WhatIf | SwitchParameter | The WhatIf switch shows what the command does without making any changes. You don't need to specify a value with this switch. | |
| -WithImportance | Importance | The WithImportance parameter specifies a condition for the Inbox rule that looks for messages with the specified importance level. Valid values are: | |
| -WithinSizeRangeMaximum | ByteQuantifiedSize | The WithinSizeRangeMaximum parameter specifies part of a condition for the Inbox rule that looks for messages that are smaller than specified maximum size. | |
| -WithinSizeRangeMinimum | ByteQuantifiedSize | The WithinSizeRangeMinimum parameter specifies part of a condition for the Inbox rule that looks for messages that are larger than the specified minimum size. | |
| -WithSensitivity | Sensitivity | The WithSensitivity parameter specifies a condition for the Inbox rule that looks for messages with the specified sensitivity level. Valid values are: |
Reference facts derived from Microsoft documentation, © Microsoft, licensed CC BY 4.0; restructured with original guidance by serv365.ai.