Using New-MgUserMailFolderMessageRule in Graph PowerShell

The New-MgUserMailFolderMessageRule cmdlet is part of the Microsoft Graph PowerShell module, enabling administrators to create new message rules within a user's mail folder. These rules can help automate email management by applying specific actions to messages that meet defined criteria. This article provides a detailed overview of the cmdlet, including syntax, usage examples, tips, use cases, and potential errors with solutions.

Note: Mail.ReadWrite is the Graph API permission you need to execute this cmdlet.

Cmdlet Syntax

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

• -UserId: Specifies the user ID or UPN (User Principal Name).
• -MailFolderId: Specifies the ID of the mail folder.
• -BodyParameter: A hashtable specifying the rule conditions and actions.

Usage Examples

Example 1: Forwarding Emails from a Specific Sender

$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

Example 2: Marking Emails with a Specific Subject 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

Cmdlet Tips

• Understanding the Conditions and Actions: The conditions and actions keys in the hashtable allow you to specify the criteria and corresponding actions for the message rule. Refer to the Microsoft documentation for a comprehensive list of available conditions and actions.
• Sequence Property: The sequence property determines the order in which the rules are executed. Ensure each rule has a unique sequence number.
• Valid Folder Paths: When specifying folder paths, ensure they are valid and exist. Incorrect paths will result in errors.

Use Cases

• Organizing Emails: Automatically move emails from specific senders or with specific subjects to designated folders.
• Filtering Spam: Delete or mark as read emails from known spam domains.
• Prioritizing Important Emails: Highlight or flag emails from critical contacts or domains.

Potential Errors and Solutions

Error: "Invalid Request"

Cause: Incorrect or missing required properties in the -BodyParameter hashtable.

Solution: Ensure all required properties are correctly specified in the hashtable. Refer to the Microsoft documentation for details.

Error: "The specified folder does not exist"

Cause: The moveToFolder action specifies a folder path that does not exist.

Solution: Verify that the specified folder path is correct and that the folder exists in the user's mailbox.

Error: "User not found"

Cause: The -UserId parameter specifies a user that does not exist.

Solution: Ensure the user ID or UPN specified in the -UserId parameter is correct and that the user exists in the tenant.

Conclusion

The New-MgUserMailFolderMessageRule cmdlet is a powerful tool for automating email management within a user's mailbox. By creating custom rules, administrators can help users maintain an organized and efficient inbox. Understanding the cmdlet's syntax, usage, and potential errors ensures successful implementation. For further details, refer to the official Microsoft documentation.

Additional Resources:

Graph PowerShell New-MgUserMailFolderMessageRule Cmdlet Documentation
Microsoft Graph PowerShell Module Documentation
Microsoft Graph API Documentation

Related Articles:

Using Get-MgDirectoryRole in Graph PowerShell
Using Get-MgUserLicenseDetail in Graph PowerShell
Using Find-GraphMgCommand in Graph PowerShell
Connect to Microsoft 365 Using PowerShell
How to Create Bulk Users in Office 365 Using Graph PowerShell?
Create Microsoft 365 Group Using Microsoft Graph PowerShell
Block Microsoft 365 User Using Microsoft Graph PowerShell
Assign Microsoft 365 License Using Graph PowerShell
Microsoft 365 User Management Using Graph PowerShell
Checking Group Membership in Microsoft 365
Bulk Assign Microsoft 365 License
Find Inactive Users in Microsoft 365
Using Powershell Graph Search Query
Using Powershell Graph Filter Query
Using Where-Object In Graph PowerShell
Using Expand Property In Graph PowerShell
Using Select Object In Graph PowerShell
Using -Contains Operator In Graph PowerShell
Add User to Multiple Microsoft 365 Groups Using Graph PowerShell
Get Microsoft 365 User Location Using Graph PowerShell
Import Microsoft 365 Groups from CSV File Using Graph PowerShell
Microsoft 365 Group User Import Using Graph PowerShell