Corporate communications, human resources, and compliance teams routinely send mandatory company-wide announcements—such as policy updates, emergency drills, or security notices. A frequent administrative request follows: "Can you generate a report showing who actually opened and read the email versus who ignored or deleted it without reading?"
Historically, administrators addressed this by writing PowerShell scripts utilizing the Exchange Web Services (EWS) Managed API and ApplicationImpersonation. However, with Microsoft's enforcement of modern authentication, deprecation of EWS, and permanent retirement of ApplicationImpersonation, those legacy scripts no longer execute.
In this modernized guide, we rebuild the email read-status auditor from the ground up using the Microsoft Graph PowerShell SDK v2 and certificate-based app-only authentication.
How Email Read-Status Works in Microsoft Graph
In Microsoft Graph, every email item in an Exchange Online mailbox is represented as a message resource. Rather than parsing through EWS SOAP XML envelopes, we query the REST endpoint /v1.0/users/{user-id}/messages.
Key message properties for read-status auditing include:
isRead(Boolean): Indicates whether the message has been opened/read ($true) or remains unread ($false).parentFolderId(String): The ID of the folder containing the message. By querying well-known folder names (Inbox,DeletedItems,Archive), we can verify whether the user deleted the announcement unread.receivedDateTime(DateTime): Timestamp when the message arrived in the user's mailbox.hasAttachments(Boolean): Confirms if policy attachments were present.
Step 1: Prerequisites & Graph Application Permissions
To query employee mailboxes without interactive logins:
- Register an application in Microsoft Entra ID named
M365-ReadReceipt-Auditor. - Assign the application permission
Mail.Read. - Upload an enterprise X.509 certificate for unattended authentication (RFC 7523).
- (Recommended) Restrict the application using an Exchange Online Application Access Policy (
New-ApplicationAccessPolicy) so the audit app can only query mailboxes within the targeted department.
Step 2: The Production Microsoft Graph PowerShell Auditor
Save the following script as Get-EmailReadStatusReport.ps1. It authenticates using your enterprise certificate and processes all target users:
#Requires -Version 5.1
<#
.SYNOPSIS
Audits whether an organization broadcast email was read, unread, or deleted.
.DESCRIPTION
Uses Microsoft Graph SDK v2 to inspect message isRead attributes across mailboxes.
#>
[CmdletBinding()]
param (
[Parameter(Mandatory = $true)]
[string]$SenderAddress,
[Parameter(Mandatory = $true)]
[string]$SubjectFilter,
[Parameter(Mandatory = $true)]
[string[]]$TargetUserPrincipalNames
)
# Authentication Configuration
$TenantId = "ab85c7a1-366d-44ba-acc6-924fa0950045"
$ClientId = "c841ae33-4093-4385-8a90-6a530761f9b9"
$CertThumbprint = "BEAC429DE404B46FF030811C0C9DE00DE701C027"
Write-Host "Authenticating to Microsoft Graph with App-Only Certificate..." -ForegroundColor Cyan
Connect-MgGraph -TenantId $TenantId -ClientId $ClientId -CertificateThumbprint $CertThumbprint -NoWelcome
$AuditResults = [System.Collections.Generic.List[PSCustomObject]]::new()
Write-Host "Searching for broadcast email: '$SubjectFilter' from '$SenderAddress'..." -ForegroundColor Yellow
foreach ($upn in $TargetUserPrincipalNames) {
Write-Host "Checking mailbox: $upn" -ForegroundColor Gray
try {
# Graph OData query filtering on sender and subject prefix
$FilterQuery = "sender/emailAddress/address eq '$SenderAddress' and startswith(subject, '$SubjectFilter')"
$Messages = Get-MgUserMessage `
-UserId $upn `
-Filter $FilterQuery `
-Select "id,subject,isRead,receivedDateTime,parentFolderId" `
-ErrorAction Stop
if (-not $Messages -or $Messages.Count -eq 0) {
$AuditResults.Add([PSCustomObject]@{
UserPrincipalName = $upn
Subject = $SubjectFilter
ReceivedDateTime = $null
IsRead = "Not Found"
FolderStatus = "Not Received / Purged"
ComplianceStatus = "Missing"
})
continue
}
foreach ($msg in $Messages) {
# Retrieve the folder name to check if deleted
$Folder = Get-MgUserMailFolder -UserId $upn -MailFolderId $msg.ParentFolderId -Select "displayName"
$FolderName = $Folder.DisplayName
$Compliance = switch ($true) {
($msg.IsRead -eq $true -and $FolderName -eq "Inbox") { "Compliant (Read)" }
($msg.IsRead -eq $false -and $FolderName -eq "Inbox") { "Pending (Unread)" }
($msg.IsRead -eq $false -and $FolderName -like "*Deleted*") { "Non-Compliant (Deleted Unread)" }
($msg.IsRead -eq $true -and $FolderName -like "*Deleted*") { "Read Then Deleted" }
Default { "Archived / Moved ($FolderName)" }
}
$AuditResults.Add([PSCustomObject]@{
UserPrincipalName = $upn
Subject = $msg.Subject
ReceivedDateTime = $msg.ReceivedDateTime
IsRead = $msg.IsRead
FolderStatus = $FolderName
ComplianceStatus = $Compliance
})
}
}
catch {
Write-Warning "Failed to query mailbox $upn : $_"
$AuditResults.Add([PSCustomObject]@{
UserPrincipalName = $upn
Subject = $SubjectFilter
ReceivedDateTime = $null
IsRead = "Error"
FolderStatus = "Access Denied / Throttled"
ComplianceStatus = "Audit Failed"
})
}
}
# Output Executive Compliance Table
$AuditResults | Format-Table -AutoSize
# Export to CSV for HR / Compliance review
$ReportPath = "C:\Reports\Email_Read_Status_Report_$(Get-Date -Format 'yyyyMMdd_HHmm').csv"
$AuditResults | Export-Csv -Path $ReportPath -NoTypeInformation
Write-Host "`n[+] Audit Report exported to: $ReportPath" -ForegroundColor Green
Sample Execution & Output
$TargetUsers = @("[email protected]", "[email protected]", "[email protected]")
.\Get-EmailReadStatusReport.ps1 `
-SenderAddress "[email protected]" `
-SubjectFilter "Mandatory Security Awareness Training" `
-TargetUserPrincipalNames $TargetUsers
Executive Report Table
UserPrincipalName Subject ReceivedDateTime IsRead FolderStatus ComplianceStatus
----------------- ------- ---------------- ------ ------------ ----------------
[email protected] Mandatory Security Awareness ... 11/12/2026 09:14:22 True Inbox Compliant (Read)
[email protected]... Mandatory Security Awareness ... 11/12/2026 09:14:23 False Inbox Pending (Unread)
[email protected].. Mandatory Security Awareness ... 11/12/2026 09:14:25 False Deleted Items Non-Compliant (Deleted Unread)
Comparing Legacy EWS vs. Modern Graph Auditor
| Feature | Legacy EWS Script | Modern Microsoft Graph SDK v2 |
|---|---|---|
| Authentication | Basic Auth / Legacy Password | App-Only Certificate (Connect-MgGraph) |
| Access Control | ApplicationImpersonation (Retired) | Scoped Mail.Read via App Access Policy |
| Protocol | Heavy SOAP XML (ExchangeService) | Fast HTTPS REST OData queries |
| Client Requirement | Microsoft.Exchange.WebServices.dll | Standard PowerShell 7 / 5.1 Graph modules |
| Folder Resolution | Multi-step folder traversal | Native parentFolderId lookup |
Summary
Migrating announcement read-status audits from legacy EWS to Microsoft Graph delivers immediate security and performance benefits. By querying isRead and parentFolderId under certificate-based authentication, enterprise administrators can deliver audit-proof compliance reports without relying on deprecated impersonation roles.