In this article

New-InboxRule

This cmdlet is available in on-premises Exchange and in the cloud-based service. Some parameters and settings may be exclusive to one environment or the other.
Use the New-InboxRule cmdlet to 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.
For information about the parameter sets in the Syntax section below, see Exchange cmdlet syntax (https://technet.microsoft.com/library/bb123552.aspx).

Description

When you create, modify, remove, enable, or disable an Inbox rule in Exchange PowerShell, any client-side rules disabled by Microsoft Outlook and outbound rules are removed.

Parameters that are used for conditions also have corresponding exception parameters. When conditions specified in an exception are matched, the rule isn't applied to the message. Exception parameters begin with ExceptIf. For example, the exception parameter for SubjectOrBodyContainsWords is ExceptIfSubjectOrBodyContainsWords.

You need to be assigned permissions before you can run this cmdlet. Although this topic lists all parameters for the cmdlet, you may not have access to some parameters if they're not included in the permissions assigned to you. To find the permissions required to run any cmdlet or parameter in your organization, see Find the permissions required to run any Exchange cmdlet (https://technet.microsoft.com/library/mt432940.aspx).

Examples

This example raises the message importance to High if the mailbox owner is in the To field. In addition, the message is flagged for action.

Required Parameters

-FromMessageId

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. For example:

MailboxId\StoreObjectId

StoreObjectId

When you use this parameter to create an Inbox rule, the following message properties are used in the rule:

Subject: The message subject is added to the SubjectContainsWords condition.

From: The message sender is added to the From condition.

To and Cc: Recipients in the To and Cc fields are added to the SentTo condition.

The ValidateOnly switch tells the cmdlet to evaluate the conditions and requirements necessary to perform the operation and then reports whether the operation will succeed or fail. No changes are made when the ValidateOnly switch is used.

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 categories separated by commas. If the value contains spaces, enclose the value in quotation marks (").

The categories that you specify for this parameter are defined in the mailbox (they aren't shared between mailboxes).

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:

NotDefined

Bills

Document

DocumentPlus

Event

Family

File

Flight

FromContact

Important

LiveView

Lodging

MailingList

Newsletter

Photo

Purchase

RentalCar

RestaurantReservation

RetiredPromotion

ShippingNotification

Shopping

SocialUpdate

Travel

Video

You can specify multiple values separated by commas.

Type:

MultiValuedProperty

Position:

Named

Default value:

None

Accept pipeline input:

False

Accept wildcard characters:

False

Applies to:

Exchange Server 2016, Exchange Online

-BodyContainsWords

The BodyContainsWords parameter specifies a condition for the Inbox rule that looks for the specified words or phrases in the body of messages.

If the phrase contains spaces, you need to enclose the value in quotation marks. You can specify multiple values separated by commas.

The corresponding exception parameter to this condition is ExceptIfBodyContainsWords.

The Confirm switch specifies whether to show or hide the confirmation prompt. How this switch affects the cmdlet depends on if the cmdlet requires confirmation before proceeding.

Destructive cmdlets (for example, Remove-* cmdlets) have a built-in pause that forces you to acknowledge the command before proceeding. For these cmdlets, you can skip the confirmation prompt by using this exact syntax: -Confirm:$false.

Most other cmdlets (for example, New-* and Set-* cmdlets) don't have a built-in pause. For these cmdlets, specifying the Confirm switch without a value introduces a pause that forces you acknowledge the command before proceeding.

The CopyToFolder parameter specifies an action for the Inbox rule that copies messages to the specified mailbox folder. You can specify the existing folder by name, or by the store object ID and a path string (for example, \Inbox\Personal).

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:

NotDefined

Bills

Document

DocumentPlus

Event

Family

File

Flight

FromContact

Important

LiveView

Lodging

MailingList

Newsletter

Photo

Purchase

RentalCar

RestaurantReservation

RetiredPromotion

ShippingNotification

Shopping

SocialUpdate

Travel

Video

You can specify multiple values separated by commas.

Type:

MultiValuedProperty

Position:

Named

Default value:

None

Accept pipeline input:

False

Accept wildcard characters:

False

Applies to:

Exchange Server 2016, Exchange Online

-DomainController

This parameter is available only in on-premises Exchange.

The DomainController parameter specifies the domain controller that's used by this cmdlet to read data from or write data to Active Directory. You identify the domain controller by its fully qualified domain name (FQDN). For example, dc01.contoso.com.

Type:

Fqdn

Position:

Named

Default value:

None

Accept pipeline input:

False

Accept wildcard characters:

False

Applies to:

Exchange Server 2010, Exchange Server 2013, Exchange Server 2016

-ExceptIfBodyContainsWords

The ExceptIfBodyContainsWords parameter specifies an exception for the Inbox rule that looks for the specified words or phrases in the body of messages.

If the phrase contains spaces, you need to enclose the value in quotation marks. You can specify multiple values separated by commas.

The corresponding condition parameter to this exception is BodyContainsWords.

The ExceptIfFromSubscription parameter specifies an exception for the Inbox rule that looks for messages received from subscriptions (for example, POP or IMAP subscriptions). You can identify the subscription by using the Get-Subscription cmdlet.

The corresponding condition parameter to this exception is FromSubscription.

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 Get-MessageClassification cmdlet. You can specify multiple message classifications separated by commas.

The corresponding condition parameter to this exception is HasClassification.

The ExceptIfReceivedAfterDate parameter specifies an exception for the Inbox rule that looks for messages received after the specified date.

Use the short date format that's defined in the Regional Options settings on the computer where you're running the command. For example, if the computer is configured to use the short date format mm/dd/yyyy, enter 09/01/2015 to specify September 1, 2015. You can enter the date only, or you can enter the date and time of day. If you enter the date and time of day, enclose the value in quotation marks ("), for example, "09/01/2015 5:00 PM".

The corresponding condition parameter to this exception is ReceivedAfterDate.

The ExceptIfReceivedBeforeDate parameter specifies an exception for the Inbox rule that looks for messages received before the specified date.

Use the short date format that's defined in the Regional Options settings on the computer where you're running the command. For example, if the computer is configured to use the short date format mm/dd/yyyy, enter 09/01/2015 to specify September 1, 2015. You can enter the date only, or you can enter the date and time of day. If you enter the date and time of day, enclose the value in quotation marks ("), for example, "09/01/2015 5:00 PM".

The corresponding condition parameter to this exception is ReceivedBeforeDate.

The ExceptIfSentTo parameter specifies an exception that looks for recipients in messages. You can use any value that uniquely identifies the recipient. For example:

Name

Distinguished name (DN)

Display name

Email address

GUID

To enter multiple values, use the following syntax: <value1>,<value2>,...<valueX>. If the values contain spaces or otherwise require quotation marks, use the following syntax: "<value1>","<value2>",..."<valueX>".

The Force switch specifies whether to suppress warning or confirmation messages. You can use this switch to run tasks programmatically where prompting for administrative input is inappropriate. You don't need to specify a value with this switch.

A confirmation prompt warns you if the mailbox contains rules that were created by Outlook, because any client-side rules will be removed by the actions of this cmdlet.

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.

The FromSubscription parameter specifies a condition for the Inbox rule that looks for messages received from subscriptions (for example, POP or IMAP subscriptions). You can identify the subscription by using the Get-Subscription cmdlet.

The corresponding exception parameter to this condition is ExceptIfFromSubscription.

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 cmdlet. You can specify multiple message classifications separated by commas.

The corresponding exception parameter to this condition is ExceptIfHasClassification.

The MoveToFolder parameter specifies an action for the Inbox rule that moves messages to the specified mailbox folder. You can specify the existing folder by name, or by the store object ID and a path string (for example, \Inbox\Personal).

The ReceivedAfterDate parameter specifies a condition for the Inbox rule that looks for messages received after the specified date.

Use the short date format that's defined in the Regional Options settings on the computer where you're running the command. For example, if the computer is configured to use the short date format mm/dd/yyyy, enter 09/01/2015 to specify September 1, 2015. You can enter the date only, or you can enter the date and time of day. If you enter the date and time of day, enclose the value in quotation marks ("), for example, "09/01/2015 5:00 PM".

The corresponding exception parameter to this condition is ExceptIfReceivedAfterDate.

The ReceivedBeforeDate parameter specifies a condition for the Inbox rule that looks for messages received before the specified date.

Use the short date format that's defined in the Regional Options settings on the computer where you're running the command. For example, if the computer is configured to use the short date format mm/dd/yyyy, enter 09/01/2015 to specify September 1, 2015. You can enter the date only, or you can enter the date and time of day. If you enter the date and time of day, enclose the value in quotation marks ("), for example, "09/01/2015 5:00 PM".

The corresponding exception parameter to this condition is ExceptIfReceivedBeforeDate.

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 parameter instructs Exchange to stop processing additional rules if the conditions of this Inbox rule are met.

$true: Stop processing more rules.

$false: The action isn't used (continue processing more rules after this one).

The WhatIf switch simulates the actions of the command. You can use this switch to view the changes that would occur without actually applying those changes. You don't need to specify a value with this switch.

Outputs

To see the return types, which are also known as output types, that this cmdlet accepts, see Cmdlet Input and Output Types (https://go.microsoft.com/fwlink/p/?LinkId=616387). If the Output Type field is blank, the cmdlet doesn't return data.