New-TransportRule

 

Applies to: Exchange Server 2007 SP1, Exchange Server 2007 SP2, Exchange Server 2007 SP3

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>]]

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.

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.

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."

$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)