How to Use New-MgUserMailFolderMessageRule to Create User Mail Folder Rules?

Automating email organization is one of the best ways to keep your inbox clean and efficient. As an admin or power user, being able to set up rules programmatically using PowerShell can save tons of time—especially across multiple users.

In this guide, we’ll walk you through the New-MgUserMailFolderMessageRule cmdlet and show how to create email rules directly in a user’s mailbox using Microsoft Graph PowerShell.

What is New-MgUserMailFolderMessageRule?

New-MgUserMailFolderMessageRule is a Microsoft Graph PowerShell cmdlet that allows you to create rules for specific mail folders in a user's mailbox. These rules automatically take actions on incoming messages based on defined conditions.

Think of it like Outlook rules—but set via script, perfect for bulk automation or remote configuration.

Why Use New-MgUserMailFolderMessageRule?

This cmdlet is incredibly helpful when you want to:

• Automatically manage inbox content
• Redirect or forward emails
• Reduce manual email triage
• Enforce compliance policies
• Script email rules across users during onboarding or audits

No need to rely on users manually setting up their rules—just automate it!

Cmdlet Syntax

New-MgUserMailFolderMessageRule -UserId <String> -MailFolderId <String> -BodyParameter <Hashtable>

Parameters:

• UserId: The user’s UPN or ID (e.g., user@domain.com)
• MailFolderId: Folder where the rule should be applied (commonly "Inbox")
• BodyParameter: A hashtable defining the rule's display name, conditions, and actions

Usage Examples

Forwarding Emails from a Specific Sender

Automatically forward emails from any address that contains gmail.com:

$params = @{
        displayName = "Forward Emails from Gmail"
        sequence = 1
        conditions = @{
            senderContains = @("gmail.com")
        }
    actions = @{
    forwardTo = @(
        @{
            emailAddress = @{
                name = "Another User"
                address = "anotheruser@domain.com"
            }
        }
    )
    stopProcessingRules = $true
    }
}

New-MgUserMailFolderMessageRule -UserId "samadmin@7xh7fj.onmicrosoft.com" -MailFolderId "Inbox" -BodyParameter $params
                                        

This is ideal for redirecting certain emails to another recipient automatically.

Marking Emails with a Specific Subject as Read

Automatically mark emails containing the word “Sale” in the subject line as read:

$params = @{
        displayName = "Mark Sale Emails as Read"
        sequence = 2
        conditions = @{
        subjectContains = @("Sale")
    }
    actions = @{
        markAsRead = $true
        stopProcessingRules = $true
    }
}
                                        
New-MgUserMailFolderMessageRule -UserId "samadmin@7xh7fj.onmicrosoft.com" -MailFolderId "Inbox" -BodyParameter $params
                                        

Great for decluttering promotional content or categorizing updates silently.

Frequently Asked Questions

• Can I apply rules to folders other than the Inbox?

Yes. Just pass the MailFolderId of the folder you want. Use Get-MgUserMailFolder to find folder IDs.

• How do I ensure my rule runs first?

Use the sequence property. Lower numbers run first.

• Can I apply multiple actions in a rule?

Absolutely. Actions like markAsRead, moveToFolder, forwardTo, and more can be combined.

• Will this rule apply retroactively?

No. Rules only apply to new incoming messages from the moment they're created.

Use Cases

• Auto-Forwarding External Emails

Redirect specific messages to another monitored mailbox.

• Mailbox Cleanup Rules

Automatically mark or move newsletters, alerts, or sales emails.

• Inbox Routing for Executives

Create priority-based rules to direct important emails to specific folders.

• Reporting and Archiving

Forward or copy emails to archiving accounts or distribution lists for compliance.

Conclusion

The New-MgUserMailFolderMessageRule cmdlet makes it easy to set up smart inbox management rules across your Microsoft 365 environment. Whether you're automating workflows, decluttering inboxes, or enforcing organizational policies, this tool lets you create efficient, scalable mail rules with just a few lines of PowerShell.