Using the Exchange Import-Export Graph API to Access Group Mailboxes

Import-Export API Gives Access to More Group Mailbox Data

As an MVP, I guess it’s not a surprise that Martin Heusser comes up with many interesting insights. He challenged my conclusion when I published an article about the lack of Microsoft Graph support for group mailboxes and pointed out that he could access group mailbox data through other APIs. True to form, Martin published a comprehensive article showing how to use the Exchange Import-Export Graph API to retrieve folders and items from group mailboxes.

I still think I am right but appreciate where he comes from. The Exchange Import-Export API certainly enables access to group mailbox data where the Outlook mailbox API cannot go, but the API is designed to facilitate operations such as backup and restore (Microsoft would prefer third-party vendors to use the Microsoft 365 Backup API).

Microsoft introduced the Import Export API as part of its initiative to retire Exchange Web Services from Exchange Online, so the Import Export API focuses on retrieving large quantities of mailbox objects. This is not a general-purpose API like the Outlook mailbox API and requires more work to extract useful information.

Navigating within Group Mailboxes

In any case, let’s examine how to navigate within group mailboxes to discover folders other than the Inbox using some of the techniques advanced by Martin. The first step is to identify a target group mailbox:

$Group = Get-MgGroup -Filter "displayName eq 'Support Tickets'"
$Group

DisplayName     Id                                   MailNickname   Description     GroupTypes
-----------     --                                   ------------   -----------     ----------
Support Tickets fd18c1e0

Now run the Exchange Get-MailboxFolderStatistics cmdlet to fetch the folders from the group mailbox and extract the display name, mailbox GUID, and identifier for each folder. Then select the folder that you’re interested in from the array of folders returned by Get-MailboxFolderStatistics.

[array]$Folders = Get-MailboxFolderStatistics -Identity fd18c1e0-14a1-4ec7-80e4-1b81fd17f02f | Select-Object Name, ContentMailboxGuid, FolderId
$Folder = $Folders | Where-Object {$_.Name -eq 'Testing'}
$FolderId = $Folder.FolderId

The folder identifier reported by Get-MailboxFolderStatistics is not in a format usable by the Graph. This doesn’t matter because the Import-Export API returns its own folder identifiers when it retrieves mailbox folders. Those identifiers can be used directly to fetch mailbox items. However, we do need the ContentMailboxGuid property because that identifies the mailbox.

Using the Exchange Import-Export API to Retrieve Group Mailbox Data

Using the Exchange Admin Import-Export API to retrieve data from group mailboxes requires the signed-in session to have the MailboxItem.Read.All and MailboxFolder.Read.All permissions and to hold either the Exchange Administrator or Global Administrator role. If you use app-only mode or an Azure Automation runbook, remember to make sure that the app or the automation account holds the Exchange administrator role. Because I ran the script with app-only authentication, application permissions are used.

The Exchange Import-Export API uses a specific format of mailbox identifier composed of the tenant identifier and a mailbox GUID (retrieved by Get-MailboxFolderStatistics):

$TenantId = (Get-MgContext).TenantId
$MailboxGuid = $Folder.ContentMailboxGuid.Guid
$MailboxId = ("MBX:{0}@{1}" -f $MailboxGuid, $TenantId)
$MailboxId = [uri]::EscapeDataString($MailboxId)
$MailboxUri = ("https://graph.microsoft.com/v1.0/admin/exchange/mailboxes/{0}/folders?`$top=200" -f $MailboxId)

Run the request to find the set of folders in the group mailbox and extract the target folder from the returned set:

[array]$Folders = Invoke-MgGraphRequest -Method GET -Uri $MailboxUri -OutputType PSObject | Select-Object -ExpandProperty Value
$MailboxFolder = $Folders | Where-Object {$_.DisplayName -eq 'Beta'}

Use of Single Value Extension Properties for Mailbox Items

Some of the more interesting information about mailbox items is represented by the Import-Export API as MAPI single value extended properties. A list of the most common properties are shown below:

Property	Tag	Graph Id
Subject	0x0037	String 0x0037
HTML Body	0x1013	Binary 0x1013
Body Text	0x1000	String 0x1000
Has Attachments	0x0E1B	Boolean 0x0E1B
Sender Name	0x0C1A	String 0x0C1A
Sender Email Address	0x0C1F	String 0x0C1F
Message Size	0x0E08	Long 0x0E08
Sent Time	0x0039	SystemTime 0x0039
Received Time	0x0E06	SystemTime 0x0E06

The Outlook mailbox API exposes most of the message properties you might want to use when working with messages. However, the Outlook mailbox API doesn’t expose message size as a property. It’s an example of a message attribute that’s available through a single value extended property but not exposed directly as a standard Outlook mailbox API property. This article describes an example of message size being retrieved by the Outlook mailbox API. Retention tags applied to Exchange messages are also held in single value extension properties.

Unlike when fetching message items using the Outlook mailbox API, single value extension properties must be expanded and included in the set retrieved by a query. This query finds the 500 most recent items in the target folder. Pagination (not shown here) might be needed to retrieve more items. For the demo, we retrieve the last 500 items from the folder.

$propertyFilter = "id eq 'String 0x0037' or id eq 'String 0x1035' or id eq 'String 0x1000' or id eq 'Binary 0x1013' or id eq 'Boolean 0x0E1B' or id eq 'Binary 0x3013' or id eq 'String 0x0C1A' or id eq 'String 0x0C1F'"
$encodedPropertyFilter = [uri]::EscapeDataString($propertyFilter)

$MailboxItemsUri = ("https://graph.microsoft.com/v1.0/admin/exchange/mailboxes/{0}/folders/{1}/items?`$top=500&`$expand=singleValueExtendedProperties(`$filter=$EncodedPropertyFilter)" -f $MailboxId, $MailboxFolder.Id)

[array]$Data = Invoke-MgGraphRequest -Uri $MailBoxItemsUri -Method GET -OutputType PsObject | Select-Object -ExpandProperty Value

After retrieving the item data from the folder, we can list some details about the items:

$Data | Format-Table CreatedDateTime, Size, @{n="Subject"; e= {($_.singleValueExtendedProperties | Where-Object Id -eq 'String 0x37').Value}}

createdDateTime      size Subject
---------------      ---- -------
28/09/2019 21:38:07 35886 The mailbox size of James Joyce exceeds the quota warning threshold
28/09/2019 21:37:35 35851 The mailbox size of Jake Adams exceeds the quota warning threshold
28/09/2019 21:37:35 35851 The mailbox size of Jake Adams exceeds the quota warning threshold
28/09/2019 21:37:33 35884 The mailbox size of John Hubbard exceeds the quota warning threshold
28/09/2019 21:37:32 35854 The mailbox size of John Adams exceeds the quota warning threshold

As you can see, the posts are all terribly interesting!

Investigating with a Complete Script

Merely describing how an API works is valuable. Putting things together in a script to do real work reveals much more about the strengths and weaknesses of an API, including taking care of issues such as performance and permissions. I therefore wrote a script (available from the Microsoft 365 for IT Pros GitHub repository) to report all the folders which hold more than 25 items for all Outlook groups in a tenant. The script uses app-only authentication for both the Microsoft Graph and Exchange Online and:

• Finds the set of Outlook groups. I found that the fastest method is to use Get-MgGroup to find Microsoft 365 Groups, then run Get-MgTeam to find team-enabled groups and find Outlook groups as the set of Microsoft 365 groups which are not team-enabled.
• For each group, runs the Get-MailboxFolderStatistics cmdlet to find folders containing items. Many folders are dropped at this point, like Sync Issues and Recoverable Items. The script only processes groups when 25 or more items exist in the Inbox. Any other group is deemed to be unused.
• For each group, use the Import Export API to find the set of available folders in the group mailbox. The script only goes one level deep when finding child folders (although not documented, the API supports navigation to find child folders from a folder root). I don’t know of many who nest folders at deeper levels within group mailboxes.
• For each folder with items, find the items and retrieve their properties for reporting.
• Generate a report. For demonstration purposes, I created an HTML report showing the senders for posts found in group mailbox folders (Figure 1). Depending on your needs, you might create other reports from the available data.

Limited API Not Intended for Reporting

This exercise has been an interesting technical investigation into a backwater of Microsoft 365. I doubt that much will come from the knowledge, except that it might interest a few who really want to know how many items and what kind of items exist outside the Inbox folder in Outlook groups.

The Import-Export API works for this kind of investigation, but its design and limitations make it awkward for reporting. Having explored what the API can do, I doubt that I’ll use it again.

---

Learn how to use Exchange Online and to exploit the data available to Microsoft 365 tenant administrators through the Microsoft 365 for IT Pros eBook. We love figuring out how things work.