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