PowerShell

Retrieving Unread Emails with Graph PowerShell

As an administrator, keeping an eye on users’ email activities is critical, especially when troubleshooting or ensuring that important communications are not missed. Whether it's a shared mailbox, a VIP user's inbox, or simply tracking unread messages for compliance purposes, automation can help reduce manual monitoring. With Microsoft Graph PowerShell, you can automate the process of retrieving unread emails for specific users, saving time and effort.

In this article, we'll walk you through a simple yet powerful PowerShell script that leverages Microsoft Graph to retrieve unread emails from any user’s inbox in your Microsoft 365 environment.

The Script: Retrieve Unread Emails for a Specific User

# Connect to Microsoft Graph
Connect-MgGraph -Scopes "Mail.ReadBasic.All"

# Define the user whose unread emails you want to retrieve
$UserId = "user@yourdomain.com"

# Retrieve unread emails from the user's inbox
$unreadEmails = Get-MgUserMessage -UserId $UserId -Filter "isRead eq false" -Property Subject, ReceivedDateTime, Sender | Select-Object Subject, ReceivedDateTime, Sender

# Display unread emails
if ($unreadEmails.Count -gt 0) {
    $unreadEmails | Format-Table -Property Subject, ReceivedDateTime, Sender
} else {
    Write-Host "No unread emails found for $UserId."
}

# Disconnect from Microsoft Graph
Disconnect-MgGraph

How the Script Works

Connect-MgGraph: The first step is connecting to Microsoft Graph. This requires authentication with the necessary API permissions. In this case, we’re using the scope Mail.ReadBasic.All, which allows the script to retrieve unread emails from users' mailboxes.
$UserId: The script defines the UserId, which corresponds to the email address (User Principal Name) of the user whose mailbox you want to query. Replace this with the specific user or use input from a file for bulk operations.
Get-MgUserMessage: This cmdlet retrieves email messages for the user. The script uses the -Filter parameter to search only for unread emails (isRead eq false) returning only specific properties like Subject, ReceivedDateTime, and Sender.
Format-Table: The unread messages are displayed in a table format with easy-to-read columns: Subject, Received Date, and Sender.
Disconnect-MgGraph: Once the task is complete, it's good practice to disconnect from Microsoft Graph to end the session.

Further Enhancements

While this script is effective in retrieving unread emails, it can be expanded further for additional functionality and flexibility:

Export Results to CSV: You can save the output to a CSV file for further analysis or reporting.

$unreadEmails | Export-Csv -Path "C:\Reports\UnreadEmails.csv" -NoTypeInformation

Monitor Multiple Users: You can modify the script to loop through a list of users from a CSV file to monitor multiple mailboxes.

$users = Import-Csv "C:\UsersList.csv"
foreach ($user in $users) {
    $unreadEmails = Get-MgUserMessage -UserId $user.UserPrincipalName -Filter "isRead eq false" -Property Subject, ReceivedDateTime, Sender
    $unreadEmails | Export-Csv -Path "C:\Reports\UnreadEmails_$($user.UserPrincipalName).csv" -NoTypeInformation
}

Filtering by Date Range: Add a filter for retrieving unread emails within a specific date range.

$startDate = (Get-Date).AddDays(-7).ToString("yyyy-MM-dd")
$unreadEmails = Get-MgUserMessage -UserId $UserId -Filter "isRead eq false and receivedDateTime ge $startDate"

Retrieve Full Message Content: You can expand the properties returned by the Get-MgUserMessage cmdlet to include the message body, attachments, and more for a deeper analysis.

Possible Errors & Solutions

Error	Cause	Solution
Insufficient Privileges to Complete the Operation	The connected account doesn’t have the required API permissions.	Ensure the user or application has the `Mail.ReadBasic` or `Mail.Read` permissions.
The term 'Connect-MgGraph' is not recognized	The Microsoft Graph PowerShell module is not installed.	Install the module using `Install-Module Microsoft.Graph`.
Invalid Filter Clause	The OData filter syntax might be incorrect or properties may be case-sensitive.	Double-check the filter syntax ensuring that properties such as `isRead` are in the correct case and formatted properly.

Conclusion

With Microsoft Graph PowerShell, administrators can automate various tasks related to email management in Microsoft 365. This simple script to retrieve unread emails for specific users is just one example of how PowerShell and Graph can simplify day-to-day monitoring tasks. It can be further enhanced for reporting, applied to multiple mailboxes, or combined with other scripts for broader automation.

The flexibility of the Graph API and PowerShell makes it a valuable toolset for administrators aiming to streamline processes and boost productivity in managing Microsoft 365 environments.