Many Mailbox Settings Missing from Outlook Settings API

One of the curious things about the Graph APIs is the incomplete Outlook settings API. It’s a well-known fact that Microsoft has not done a good job of supporting Exchange management operations through the Graph API. Perhaps understandably because of its long-term history with Exchange, PowerShell is the current focal point for Exchange Management automation

Perhaps the Outlook settings API is the starting point for what will become a full-fledged implementation to manage all aspects of mailbox settings. Given the scheduled retirement of Exchange Web Services (EWS) from October 2026. If so, an API covering all aspects of mailbox configuration would be a welcome development. PowerShell is great, but a Graph API is more flexible because of its support. With that thought in mind, let’s review what the current API can do.

Different Clients, Different Settings

Outlook classic (Win32) and OWA (or the new Outlook for Windows) use different client settings. Some crossover exists, such as roaming signatures, but the different history for the clients means that settings are divided into those stored in the system registry (Outlook classic) and those held in user mailboxes (OWA).

Exchange Online supports cmdlets like Get-MailboxCalendarConfiguration to manage mailbox settings, but the Outlook settings API only deals with a limited subset of the settings exposed through the OWA client (Figure 1).

Properties Returned by the Outlook Settings API

The properties returned by the Outlook Settings API are:

• Auto-replies (automaticRepliesSetting).
• Date format (dateFormat).
• Delegate message delivery options (delegateMeetingMessageDeliveryOptions).
• Locale (localeInfo).
• Time format (timeFormat).
• Time zone (timezone).
• Working hours (workingHours)
• User purpose or mailbox type (userPurpose).

The Get-MgUserMailboxSettings cmdlet returns all the properties supported by the Outlook Settings API. Here’s how to fetch the settings for the currently signed-in user:

Connect-MgGraph -Scopes MailboxSettings.ReadWrite
$User = Get-MgUser -UserId (Get-MgContext).Account
[Array]$Settings = Get-MgUserMailboxSetting -UserId $User.Id

$Settings | Format-Table

ArchiveFolder                         : AAMkADAzNzBmMzU0LTI3NTItNDQzNy04NzhkLWNmMGU1MzEwYThkNAAuAAAAAAB_7ILpFNx8TrktaK8VYWerAQA3tTkMTDKYRI6zB9VW59QNAABnZQYBAAA=
AutomaticRepliesSetting               : Microsoft.Graph.PowerShell.Models.MicrosoftGraphAutomaticRepliesSetting
DateFormat                            : d MMM yyyy
DelegateMeetingMessageDeliveryOptions : sendToDelegateAndPrincipal
Language                              : Microsoft.Graph.PowerShell.Models.MicrosoftGraphLocaleInfo
TimeFormat                            : HH:mm
TimeZone                              : GMT Standard Time
UserPurpose                           : user
WorkingHours                          : Microsoft.Graph.PowerShell.Models.MicrosoftGraphWorkingHours

To reveal full details of a setting shown with a Graph object type rather than a value, pipe the property to the Format-List cmdlet:

$Settings.Language | Format-List

DisplayName          : English (Ireland)
Locale               : en-IE
AdditionalProperties : {}

As a practical example of using the API, here’s how to configure auto-replies. The example configures a simple HTML auto-reply message for both external and internal senders to be sent during a scheduled period extending from now to 30 days in the future. Details of the different values available to configure the autoreply settings are available online. This code uses some simple hash tables to hold the parameters (for those who care, I find this technique easier and less probe to error than composing a request body in JSON, especially when nesting values).

to error than composing a request body in JSON).
[array]$Settings = Get-MgUserMailboxSetting -UserId $User.Id
$Timezone = $Settings.TimeZone

$Start = Get-Date (Get-Date).AddHours(-2)-format s
$End = Get-Date (Get-Date).AddDays(+30) -format s

$StartDateTime = @{}
$StartDateTime.Add("dateTime", $Start)
$StartDateTime.Add("timezone", $TimeZone)

$EndDateTime = @{}
$EndDateTime.Add("dateTime", $End)
$EndDateTime.Add("timezone", $TimeZone)

$Parameters = @{}
$Parameters.Add("Status", "scheduled")
$Parameters.Add("externalAudience","all")
$Parameters.Add("internalreplymessage",$HtmlMessage)
$Parameters.Add("externalreplymessage",$HtmlMessage)
$Parameters.Add("scheduledEndDateTime",$EndDateTime)
$Parameters.Add("scheduledStartDateTime",$StartDateTime)

$AutoRepliesSetting = @{}
$AutoRepliesSetting.Add("automaticRepliesSetting", $Parameters)
Update-MgUserMailboxSetting -UserId $User.id -BodyParameter $AutoRepliesSetting

The effect of the update to mailbox settings is shown in Figure 2.

OWA and Outlook classic share most auto-reply settings. Three settings specific to OWA are shown under the scheduled period, like “block my calendar for this period.” These settings are not available in Outlook classic and unsupported by the Outlook settings API. Auto-reply settings can be set using the Exchange Online Set-MailboxAutoReplyConfiguration cmdlet, as in this example of configuring auto-replies for shared mailboxes to respond to incoming customer queries over a holiday period.

The Archive Folder

I’m not quite sure why the settings include the mailbox folder identifier for the Archive folder. The Archive folder is one of Outlook’s default mailbox folders and has nothing to do with the online archive. The folder identifier might be present to tell Outlook the target folder when executing the move to archive action.

In any case, an API exists to translate folder identifiers between different formats. The value is stored as a “RestID,” which is the default used by the Graph. Here’s how to translate the identifier to the MAPI format, which is what you’d see when browsing mailbox contents with the MFCMAPI utility.

[array]$SourceIds = $Settings.ArchiveFolder
$Body = @{}
$Body.Add("sourceIdType", "RestId")
$Body.Add("inputIds", $SourceIds)
$Body.Add("targetIdType", "entryid")

$R = Invoke-MgTranslateUserExchangeId -UserId Rene.Artois@office365itpros.com -BodyParameter $Body
Write-Host ("REST format identifier is {0}" -f $R.SourceId)
Write-Host ("MAPI format identifier is {0}" -f $R.TargetId)
REST format identifier is AAMkAGU2MDhlMDhjLTdlZGMtNDMwNC05M2Y4LTIyNzNiYzI5N2VlNwAuAAAAAAC8kIa3heviTIMxxfhY7u2KAQB7Y5w0HV7-Rou7AD9UAhLGAAAAAAE9AAA=
MAPI format identifier is AAAAALyQhreF6-JMgzHF-Fju7YoBAHtjnDQdXv9Gi7sAP1QCEsYAAAAAAT0AAA2

To see more of the gory details about item and folder identifier formats, see Vasil’s blog.

Good in Parts

The Outlook settings API is like a curate’s egg: good in parts. It seems like something Microsoft started on some time ago (look at the 2016 dates used in the update examples) and then forgot. If so, that’s a pity. It would be nice to have full Graph coverage of all Microsoft 365 workload. We’re still waiting and looks like we’ll have to wait for a while yet.

Keep up with the changing world of the Microsoft 365 ecosystem by subscribing to the Office 365 for IT Pros eBook. Monthly updates mean that our subscribers learn about new developments as they happen.