Applies to: Exchange Server 2007 SP3, Exchange Server 2007 SP2, Exchange Server 2007 SP1
Topic Last Modified: 2007-08-13

Use the New-TransportRule cmdlet to create a new transport rule that the Transport Rules agent uses when it processes e-mail messages that pass through a computer that has the Microsoft Exchange Server 2007 Hub Transport server role or the Edge Transport server role installed.

Syntax


`New-TransportRule -Name <String> -Actions <TransportRuleAction[]> [-Comments <String>] [-Conditions <TransportRulePredicate[]>] [-Confirm [<SwitchParameter>]] [-DomainController <Fqdn>] [-Enabled <$true \| $false>] [-Exceptions <TransportRulePredicate[]>] [-Priority <Int32>] [-TemplateInstance <PSObject>] [-WhatIf [<SwitchParameter>]]`

Parameters

Parameter	Required	Type	Description
Actions	Required	Microsoft.Exchange.MessagingPolicies.Rules.Tasks.TransportRuleAction[]	Use this parameter to specify the actions that the transport rule applies to the e-mail message if all conditions are met and if no exceptions are met. At least one action must be specified for each rule.
Name	Required	System.String	Use this parameter to specify the display name of the transport rule to be created. The length of the name cannot exceed 64 characters.
Comments	Optional	System.String	Use this parameter to add informative comments to the rule, such as what the rule is used for or how it has changed over time. The length of the comment cannot exceed 1024 characters.
Conditions	Optional	Microsoft.Exchange.MessagingPolicies.Rules.Tasks.TransportRulePredicate[]	Use this parameter to specify the conditions that are applied by the transport rule to e-mail messages that are submitted to the Transport Rules agent. If you do not configure a condition on a rule, the rule will be applied to all messages if no exceptions are matched.
Confirm	Optional	System.Management.Automation.SwitchParameter	The Confirm parameter causes the command to pause processing and requires you to acknowledge what the command will do before processing continues. You don't have to specify a value with the Confirm parameter.
DomainController	Optional	Microsoft.Exchange.Data.Fqdn	To specify the fully qualified domain name (FQDN) of the domain controller that retrieves data from the Active Directory directory service, include the DomainController parameter in the command. The DomainController parameter is not supported on computers that run the Edge Transport server role. The Edge Transport server role writes only to the local Active Directory Application Mode (ADAM) instance.
Enabled	Optional	System.Boolean	Use this parameter to specify whether the transport rule should be enabled or disabled when it is created. The default value is `$true`.
Exceptions	Optional	Microsoft.Exchange.MessagingPolicies.Rules.Tasks.TransportRulePredicate[]	Use this parameter to specify the exceptions that the transport rule applies to the e-mail message. If a message matches any exception, no action that is specified on this rule is applied to the message.
Priority	Optional	System.Int32	Use this parameter to specify the order in which the transport rules are applied. If you modify the priority of the rule, the position of the rule in the rule list changes to match the priority that you specified, and the Transport Rules agent increments all rules with a higher priority value. Rules with a lower priority value are processed first. The value of this parameter must be greater than or equal to 0.
TemplateInstance	Optional	System.Management.Automation.PSObject	When an existing object is supplied to this parameter, the command uses the configuration of that object to create an identical copy of the object on a local or target server. For more information, see Templates.
WhatIf	Optional	System.Management.Automation.SwitchParameter	The WhatIf parameter instructs the command to simulate the actions that it would take on the object. By using the WhatIf parameter, you can view what changes would occur without having to apply any of those changes. You don't have to specify a value with the WhatIf parameter.

Detailed Description

The New-TransportRule cmdlet enables you to create a new transport rule that the Transport Rules agent uses when it processes e-mail messages that pass through a Hub Transport server or the Edge Transport server in an Exchange 2007 organization.

Each condition and exception must use a supported rule predicate. Each predicate consists of the predicate itself and the value that you want to test for.

For a list of supported transport rule predicates, see Transport Rule Predicates.

Each action must use a supported rule action. Each action consists of the action itself and the values that the action uses to perform its task.

For a list of supported transport rule actions, see Transport Rule Actions.

For detailed information about how to create a new transport rule, see How to Create a New Transport Rule.

For information about the Transport Rules agent, see Overview of Transport Rules.

To run the New-TransportRule cmdlet, the account you use must be delegated the following:

Exchange Organization Administrator role

To run the New-TransportRule cmdlet on a computer that has the Edge Transport server role installed, you must log on by using an account that is a member of the local Administrators group on that computer.

For more information about permissions, delegating roles, and the rights that are required to administer Exchange 2007, see Permission Considerations.

Input Types

Return Types

Errors

Error	Description

Exceptions

Exceptions	Description

Example

The following example shows how to create a new transport rule on a Hub Transport server.

This rule applies the following conditions:

between distribution list and distribution list The first predicate property value for this condition is the distribution group "Sales Group". The second predicate property value for this condition is the distribution group "Brokerage Group".

The following exceptions are applied:

with text patterns in the subject The value for this exception is "Press Release" or "Corporate Communication".
from people The values for this exception are the users Ted Bremer and Pilar Ackerman.

The following actions will be applied to any messages that match the conditions that were described earlier, but do not match the "with text patterns in the subject" or "from people" exceptions:

send bounce message to sender This value for this action is "E-mail messages sent between the Sales department and the Brokerage department are prohibited."
log event with message The value for this action is "A prohibited e-mail message has been rejected."

	Copy Code
$Condition1 = Get-TransportRulePredicate BetweenMemberOf $Condition1.Addresses = @((Get-DistributionGroup "Sales Group")) $Condition1.Addresses2 = @((Get-DistributionGroup "Brokerage Group")) $Exception1 = GetTransportRulePredicate From $Exception1.Addresses = @((Get-MailUser "Ted Bremer"), (Get-MailUser "Pilar Ackerman")) $Exception2 = Get-TransportRulePredicate SubjectContains $Exception2.Words = @("Press Release", "Corporate Communication") $Action1 = Get-TransportRuleAction RejectMessage $Action1.RejectReason = "E-mail messages sent between the Sales department and the Brokerage department are prohibited." $Action2 = Get-TransportRuleAction LogEvent $Action2.EventMessage = "A prohibited e-mail message has been rejected." New-TransportRule -name "Block e-mail messages between Sales and Brokerage groups" -Condition @($Condition1) -Exception @($Exception1, $Exception2) -Action @($Action1, $Action2)

Copy Code

$Condition1 = Get-TransportRulePredicate BetweenMemberOf
$Condition1.Addresses = @((Get-DistributionGroup "Sales Group"))
$Condition1.Addresses2 = @((Get-DistributionGroup "Brokerage Group"))
$Exception1 = GetTransportRulePredicate From
$Exception1.Addresses = @((Get-MailUser "Ted Bremer"), (Get-MailUser "Pilar Ackerman"))
$Exception2 = Get-TransportRulePredicate SubjectContains
$Exception2.Words = @("Press Release", "Corporate Communication")
$Action1 = Get-TransportRuleAction RejectMessage
$Action1.RejectReason = "E-mail messages sent between the Sales department and the Brokerage department are prohibited."
$Action2 = Get-TransportRuleAction LogEvent
$Action2.EventMessage = "A prohibited e-mail message has been rejected."
New-TransportRule -name "Block e-mail messages between Sales and Brokerage groups" -Condition @($Condition1) -Exception @($Exception1, $Exception2) -Action @($Action1, $Action2)