Set-TransportRule: Update Microsoft Exchange Mail Flow Rules

Mail flow rules (a.k.a. transport rules) let you inspect messages in transit and take actions—redirect, add disclaimers, block, etc. Use Set-TransportRule to update existing rules in Exchange Online.

i) Cmdlet Syntax

Set-TransportRule -Identity <RuleIdentity> -Name <String>  [-Enabled <Boolean>] [-Priority <Int32>] [-SentTo <RecipientIdParameter[]>] [-SenderDomainIs <MultiValuedProperty>] [-SubjectContainsWords <MultiValuedProperty>]]

• Note: The mail flow rule Identity parameter is required to update transport rules reliably. You can retrieve it with:

Get-TransportRule | Select Name, Identity

• Note: While Graph PowerShell continues to evolve, it does not yet support the creation of mail flow rules. For now, you must use Exchange Online PowerShell to manage mail flow at this level. In other words, Microsoft Graph PowerShell only supports mailbox rule management, not mail flow rule management.

ii) Usage Examples

1. Redirect messages sent to a specific mailbox

Set-TransportRule -Name "Redirect CEO Emails" `
-SentTo "samadmin@7xh7fj.onmicrosoft.com" `
-RedirectMessageTo kim@7xh7fj.onmicrosoft.com


2. Block messages from a specific domain with a custom NDR reason

Set-TransportRule -Name "Block Example.com Emails" `
-SenderDomainIs "example.com" `
-RejectMessageReasonText "Emails from gmail.com are not accepted."

Tip: If multiple rules share similar names, prefer -Identity over -Name to avoid ambiguity.

iii) Cmdlet Tips

• Connect first:

Connect-ExchangeOnline

• Find the exact rule to update:

Get-TransportRule | Sort-Object Priority | Select Name, Identity, Priority, Enabled

• Use -WhatIf when testing:

Set-TransportRule -Identity "" -Enabled $false -WhatIf

• Priorities matter: Lower numbers run first. Adjust with -Priority to control evaluation order.
• Document intent: Add a change note using -Comments "why/when/who changed".
• Scope changes safely: Disable the rule (-Enabled:$false), tweak conditions/actions, then re-enable after validation.
• Audit current settings:

Get-TransportRule -Identity "" | Format-List *

iv) Use Cases

• Executive mail routing: Redirect mail sent to exec aliases to monitored mailboxes or assistants.
• Partner/domain control: Block or allow specific sender domains during incidents or vendor transitions.
• Compliance banners: Apply disclaimers for outbound mail to external recipients.
• Data protection: Detect sensitive keywords and route messages for approval or incident reporting.
• Spoof mitigation: Add conditions for unauthenticated senders with executive display names.

v) Possible Errors & Solutions

Error	Cause	Solution
The transport rule 'X' can't be found.	Wrong -Identity or -Name not unique	Use `Get-TransportRule
Parameter cannot be processed... (invalid recipient/domain)	Typo or object not resolvable	Validate recipients with Get-Recipient and verify domains are accepted/verified.
Insufficient permissions	Missing Exchange role (e.g., Organization Management)	Ensure your account has appropriate Exchange Online admin roles.
Rule updates not taking effect	Rule disabled or lower priority overshadowed by earlier rule	Confirm -Enabled $true and review/adjust -Priority.
Conflicting conditions/actions	Mutually exclusive parameters used together	Check the rule’s current config with `Get-TransportRule -Identity ""
Localization in NDR text	Custom -RejectMessageReasonText unreadable for recipients	Keep messages concise, plain English (or provide localized variants via separate rules).

Conclusion

Set-TransportRule is your go-to cmdlet for evolving mail flow policies without recreating rules. Always identify the exact rule via -Identity, test with -WhatIf, and be mindful of priority so your changes take effect as intended. For mail flow rule management, stick with Exchange Online PowerShell; Graph PowerShell remains limited to mailbox rules today.

If you’d like, I can draft a companion checklist (pre-change/post-change validation) or a rollback snippet to quickly restore previous settings.