Get-MgUserMailFolderMessage: How to Retrieve Messages from Mail Folders in Microsoft 365
This guide demonstrates how to use the Get-MgUserMailFolderMessage cmdlet in Microsoft Graph PowerShell to retrieve messages from specific mailbox folders. Learn how to filter messages, retrieve details, and export them with practical examples.
The Get-MgUserMailFolderMessage cmdlet is a powerful tool within the Microsoft Graph PowerShell module enabling administrators to retrieve messages from a specific mail folder in a user's mailbox. This article provides a detailed overview of the cmdlet including its syntax, usage examples, tips, use cases, possible errors, and solutions.
Syntax
Get-MgUserMailFolderMessage -UserId <String> -MailFolderId <String> [-Filter <String>] [-Search <String>] - UserId: Specifies the user's ID or principal name (UPN).
- MailFolderId: Specifies the mail folder's ID.
- Filter: Filters results based on specific criteria.
- Search: Searches for messages matching a specific query.
Note: You need -MailFolderId to work with this cmdlet which can got by executing Get-MgUserMailFolderMessage and passing in the UserID or UPN.
Usage Examples
Example 1: Retrieve All Messages from a Specific Folder
This command retrieves all messages from the specified folder.
Get-MgUserMailFolderMessage -UserId "user@domain.com" -MailFolderId "AAMkAGI2T" 
Example 2: Filter Messages by Date
This command retrieves messages received after January 1, 2024, from the specified folder.
Get-MgUserMailFolderMessage -UserId "user@domain.com" -MailFolderId "AAMkAGI2T" -Filter "receivedDateTime ge 2024-01-01T00:00:00Z"
Example 3: Search for Messages Containing Specific Text
This command searches for messages containing the word "Important" in the specified folder.
Get-MgUserMailFolderMessage -UserId "user@domain.com" -MailFolderId "AAMkAGI2T" -Search "Important"
Example 4: Search for Messages using Message ID
This command searches for the message based on the message ID passed to -MessageID.
Get-MgUserMailFolderMessage -UserId "user@domain.com" -MailFolderId "AAMkAGI2T" -MessageId "AAMkADA"
Cmdlet Tips
- Efficient Filtering: Use the -Filter parameter to retrieve only the necessary messages, which can improve performance.
- Property Selection: Use the -Select or -Property parameters to specify only the required properties, reducing the amount of data returned.
- Expand Property: Utilize the -ExpandProperty parameter to retrieve related entities inline, such as Attachments or Extensions.
Use Cases
- Email Auditing: Retrieve and review messages from specific folders for compliance or auditing purposes.
- Mailbox Management: Monitor and manage the contents of user mail folders, including message retrieval and analysis.
- Automated Reporting: Generate reports on email activity within specific folders for business insights and decision-making.
Possible Errors & Solutions
Error 1: Invalid User ID
Cause: The specified user ID or UPN is incorrect or does not exist.
Solution: Verify that the -UserId parameter is correct and corresponds to an existing user. Use Get-MgUser to check user details.
Get-MgUser -UserId "user@domain.com"Error 2: Invalid Mail Folder ID
Cause: The specified mail folder ID is incorrect or does not exist.
Solution: Verify that the -MailFolderId parameter is correct. Use Get-MgUserMailFolder to retrieve valid folder IDs.
Get-MgUserMailFolder -UserId "user@domain.com"Error 3: Insufficient Permissions
Cause: The executing user does not have the necessary permissions to access the specified mail folder.
Solution: Ensure that the executing user has the required permissions. This might involve granting appropriate permissions or running the cmdlet as an administrator. Mail.Read is the required Graph API permission.
Error 4: Throttling
Cause: The request is being throttled due to high usage or rate limits.
Solution: Implement retry logic in the script and adhere to Microsoft's throttling guidelines.
Start-Sleep -Seconds 30Frequently Asked Questions
1. What is Get-MgUserMailFolderMessage used for?
Get-MgUserMailFolderMessage is a Microsoft Graph PowerShell cmdlet used to retrieve email messages from a specific folder in a user’s mailbox, such as Inbox or Sent Items.
2. How can I retrieve all messages from a specific folder?
Use the following script to list all messages in a folder:
Get-MgUserMailFolderMessage -UserId "<UserPrincipalName>" -MailFolderId "<FolderId>" -All3. Can I filter messages by subject or sender?
Yes, use the -Filter parameter to filter messages. Example for filtering by subject:
Get-MgUserMailFolderMessage -UserId "<UserPrincipalName>" -MailFolderId "<FolderId>" -Filter "subject eq 'Important Update'" -All4. How can I export folder messages to a CSV file?
Use this script to export messages from a specific folder:
$Messages = Get-MgUserMailFolderMessage -UserId "<UserPrincipalName7gt;" -MailFolderId "<FolderId>" -All
$Messages | Select-Object Subject, Sender, ReceivedDateTime | Export-Csv -Path "C:\Path\To\FolderMessages.csv" -NoTypeInformation
5. What permissions are required to retrieve folder messages?
You need the Mail.Read or Mail.ReadWrite permission in Microsoft Graph PowerShell. Ensure these permissions are granted and consented in Azure AD.
Conclusion
The Get-MgUserMailFolderMessage cmdlet is a versatile tool for managing and retrieving messages from user mail folders within Microsoft 365. By understanding its syntax, usage, and potential pitfalls, administrators can effectively leverage this cmdlet for various use cases, from auditing to automated reporting. Remember to handle possible errors gracefully and optimize your queries for performance.
Additional Resources
Microsoft Graph PowerShell Module DocumentationMicrosoft Graph API Documentation
Related Articles:
Using Get-MgDirectoryRole in Graph PowerShellUsing 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