A Simple Question About Managing Microsoft 365 Retention Labels with the Microsoft Graph

A reader asked if it is possible to have scripts apply retention labels to files and email using cmdlets from the Microsoft Graph PowerShell SDK. This is an example of a question that seems like it should be easy to answer but turns out not to be the case. Let’s plunge in and explain why.

Two Types of Retention Inside Microsoft 365

Microsoft 365 supports two forms of retention labels. The first type is MRM (Messaging Records Management) retention tags, the second is Microsoft 365 retention labels. Microsoft would very much like to get rid of retention tags, and have been saying so for years. However, retiring MRM retention tags is impracticable because Microsoft 365 retention labels don’t deliver some of the features available through retention tags, such as folder-specific processing and the move to archive action.

MRM retention tags are only available for email while Microsoft 365 retention labels cover both files and email. The complexity is invisible to users because Outlook clients combine tags and labels into a common set. Figure 1 shows a list of retention tags and labels as seen in the new Outlook for Windows. Why the list isn’t sorted alphabetically as it is in Outlook classic is beyond me. Hopefully, Microsoft will sort this annoying aspect out before they discontinue support for Outlook classic in 2029.

The Exchange Managed Folder Assistant also combines tags and labels into a common set when it applies retention settings to mailboxes.

The Programmatic Issue

Microsoft has sorted the problem of different retention labels in its clients and background processing, but dealing with the two types of labels is problematic for programmatic interfaces. MRM retention tags can be applied to emails through Exchange Web Services (EWS) but not through the Microsoft Graph APIs because they deal exclusively with files.

Microsoft wants to retire EWS in October 2026 and suggest that developers should migrate their code to the Graph APIs. However, gaps exist in Graph coverage that make such a movement currently impossible, and retention labels are one such gap that Microsoft must close before it can retire EWS.

The alternative is that Microsoft enhances Microsoft 365 retention labels to add features like support for moving items to archive mailboxes. I don’t see any prospect of this happening in the short term.

An Example Script

An example script is always a great way to demonstrate how to use a Graph API. The OneDrive for Business file report script contains several examples of SDK cmdlets being used to access retention labels. Access to retention label information requires the RecordsManagement.Read.All permission, which is only available in a delegated form. The lack of an application permission might seem odd, but Microsoft 365 applications only show users the set of retention labels made available to them through label publishing policies.

One of the first steps in the script is to run the Get-MgSecurityLabelRetentionLabel cmdlet to retrieve the set of Microsoft 365 retention labels (but not MRM tags) available to the signed-in user.

[array]$RetentionLabels = Get-MgSecurityLabelRetentionLabel

The script fetches details of every file in every folder in the OneDrive account. To check if a file has a retention label, the script runs the Get-MgDriveItemRetentionLabel cmdlet and passes the drive identifier and the file identifier. The drive identifier points to a library in a SharePoint Online site or a OneDrive for Business account. Each file in the library has a unique identifier. Together, a file can always be found.

This modified form of the script code fetches the identifier for the default library in the OneDrive account of the user signed into a Graph SDK interactive session and finds all the files in the root folder. It then checks the first item to see if the file has a retention label. No values are reported in the set of retention label properties output by the cmdlet, so we know that the file is not labeled.

$User = Get-MgUser -UserId (Get-MgContext).Account
$OneDrive = Get-MgUserDrive -UserId $User.Id | Where-Object {$_.Name -like "*OneDrive*"}
[array]$Data = Get-MgDriveItemChild -DriveId $OneDrive.Id -DriveItemId "root" -All
[array]$Files = $Data | Where-Object {$null -ne $_.file.mimetype}
Get-MgDriveItemRetentionLabel -DriveId $OneDrive.Id -DriveItemId $Files[0].Id

Id IsLabelAppliedExplicitly LabelAppliedDateTime Name
-- ------------------------ -------------------- ----

Taking the concept a little further, here’s how to report the set of labeled files in the root folder of the OneDrive account.

$LabeledFiles = [System.Collections.Generic.List[Object]]::new()
ForEach ($File in $Files) {
   $FileInfo =  Get-MgDriveItemRetentionLabel -DriveId $OneDrive.Id -DriveItemId $File.Id
   If ($FileInfo.Name) {
      $ReportLine = [PSCustomObject]@{
         Label = $FileInfo.Name
         File  = $File.Name
       }
       $LabeledFiles.Add($ReportLine)
   }
}

Applying and Removing Retention Labels

The script doesn’t apply retention labels to items. If it did, it would run the Update-MgDriveItemRetentionLabel cmdlet. The cmdlet takes a hash table containing the name of the retention label to apply as its input:

$RetentionLabel = @{}
$RetentionLabel.Add("Name","Approved")
$Status = Update-MgDriveItemRetentionLabel -DriveId $OneDrive.Id -DriveItemId $File.Id -BodyParameter $RetentionLabel
If ($Status.Name) { Write-Host "Retention label assigned"}

To remove a retention label from a file, run the Remove-MgDriveItemRetentionLabel cmdlet:

Remove-MgDriveItemRetentionLabel -DriveId $OneDrive.Id -DriveItemId $File.Id

The Graph Covers SharePoint and OneDrive but not Exchange

What we’ve learned is that Microsoft Graph PowerShell SDK cmdlets are available to get, apply, and remove Microsoft 365 retention labels from items stored in SharePoint Online and OneDrive for Business sites. If you want to apply MRM retention tags to email, you’ll need to use EWS. That is, until Microsoft retires EWS in 2026…

Support the work of the Office 365 for IT Pros team by subscribing to the Office 365 for IT Pros eBook. Your support pays for the time we need to track, analyze, and document the changing world of Microsoft 365 and Office 365.