Skip to main content

EWS Managed API and Powershell How-To Series Part 7 Using the Configuration Information Operation

In the past couple of posts I've been looking at using the special operations in EWS that allow you to access the unconventional data in a mailbox such as OOF, FreeBusy etc. In this post I'm going to look at accessing the FAI (Folder Associated Items) userconfiguration Items. These are used to store a lot of the Meta-Information for various mailbox functions such as the Master Category list, Works hours, OWA Signature and various other configuration options. The best documentation for the options and formats that are used to store config information in FAI Items is the following Exchange Protocol Document http://msdn.microsoft.com/en-us/library/cc463899%28v=exchg.80%29.aspx.

Before looking at EWS you should consider whether using the Exchange Management Shell maybe a better option, most of the configuration Setting can now be set using EMS cmdlet's such as eg OWA Signature(Get-MailboxMessageConfiguration), WorkHours(Get-MailboxCalendarConfiguration).

With UserConfiguration information that is stored on a FAI item the Item will have a special ItemClass and the config data itself is stored in one or more Mapi properties in either a custom XML format,Roaming Dictionary format or Binary format. Lets look at a few examples of dealing with the different formats for different config Items

Master Category List

The first one I'll cover is the Master category list which I've shown an example of before but the Master Category list is held in a FAI item in the Mailboxes Calendar Folder with a ItemClass of IPM.Configuration.CategoryList and the data for the catergory list is held in a Mapi property in a Custom XML format that is documented in the Exchange Protocol Document i linked above.


To Access the Master Category list which is useful if you need to show the color associated with a particular Keyword.

  1. $folderid= new-object Microsoft.Exchange.WebServices.Data.FolderId([Microsoft.Exchange.WebServices.Data.WellKnownFolderName]::Calendar,$MailboxName)     
  2. #Specify the Calendar folder where the FAI Item is  
  3. $UsrConfig = [Microsoft.Exchange.WebServices.Data.UserConfiguration]::Bind($service"CategoryList"$folderid, [Microsoft.Exchange.WebServices.Data.UserConfigurationProperties]::All)  
  4. #Get the XML in String Format  
  5. $CatXML = [System.Text.Encoding]::UTF8.GetString($UsrConfig.XmlData)  
  6. #Deal with the first character being a Byte Order Mark  
  7. $boMark = $CatXML.SubString(0,1)  
  8. #Parse the XML  
  9. [XML]$CatXML = $CatXML.SubString(1)  
  10. $NewCat = $CatXML.categories.category  
If you want to add a new Category the easiest way to do this is to clone a existing category from the existing XML change the properties then append it to the Categorylist. Here's an example

  1. $folderid= new-object Microsoft.Exchange.WebServices.Data.FolderId([Microsoft.Exchange.WebServices.Data.WellKnownFolderName]::Calendar,$MailboxName)     
  2. #Specify the Calendar folder where the FAI Item is  
  3. $UsrConfig = [Microsoft.Exchange.WebServices.Data.UserConfiguration]::Bind($service"CategoryList"$folderid, [Microsoft.Exchange.WebServices.Data.UserConfigurationProperties]::All)  
  4. #Get the XML in String Format  
  5. $CatXML = [System.Text.Encoding]::UTF8.GetString($UsrConfig.XmlData)  
  6. #Deal with the first character being a Byte Order Mark  
  7. $boMark = $CatXML.SubString(0,1)  
  8. #Parse the XML  
  9. [XML]$CatXML = $CatXML.SubString(1)  
  10. #Clone exiting Entry  
  11. $NewCat = $CatXML.categories.category[0].Clone()  
  12. #Set properties  
  13. $NewCat.name = "My New Cat meow"  
  14. $NewCat.color = "10" #Steel Cat  
  15. $NewCat.keyboardShortcut = "0"  
  16. $NewCat.guid = "{" + [System.Guid]::NewGuid().ToString() + "}"  
  17. $NewCat.renameOnFirstUse = "0"  
  18. [Void]$CatXML.categories.AppendChild($NewCat)  
  19. $UsrConfig.XmlData = [System.Text.Encoding]::UTF8.GetBytes($boMark + $CatXML.OuterXml)  
  20. #Update Item  
  21. $UsrConfig.Update()  
OWA UserOptions

The most common form of data-format that is used for a configuration item is the Dictionary an example of this is the OWA.UserOptions FAI item that is held in the Root of the Mailbox. This contains the OWA configuration for the user including the OWA Signature. To show the settings that are currently held in the dictionary in this configuration Item we can use.

  1. $folderid= new-object Microsoft.Exchange.WebServices.Data.FolderId([Microsoft.Exchange.WebServices.Data.WellKnownFolderName]::Root,$MailboxName)     
  2. #Specify the Root folder where the FAI Item is  
  3. $UsrConfig = [Microsoft.Exchange.WebServices.Data.UserConfiguration]::Bind($service"OWA.UserOptions"$folderid, [Microsoft.Exchange.WebServices.Data.UserConfigurationProperties]::All)  
  4. $UsrConfig.Dictionary  
If you wanted to set the OWA Signature for a user you would use something like this

  1. $folderid= new-object Microsoft.Exchange.WebServices.Data.FolderId([Microsoft.Exchange.WebServices.Data.WellKnownFolderName]::Root,$MailboxName)     
  2. #Specify the Root folder where the FAI Item is  
  3. $UsrConfig = [Microsoft.Exchange.WebServices.Data.UserConfiguration]::Bind($service"OWA.UserOptions"$folderid, [Microsoft.Exchange.WebServices.Data.UserConfigurationProperties]::All)  
  4. $hsHtmlSigniture = "Im away use <a href='www.bing.com'>www.bing.com</a>";  
  5. $stTextSig = "Get a HTML email editor it is 2012 you know";  
  6. if($UsrConfig.Dictionary.ContainsKey("signaturehtml")){  
  7.     $UsrConfig.Dictionary["signaturehtml"] = $hsHtmlSigniture  
  8. }  
  9. else{  
  10.     $UsrConfig.Dictionary.Add("signaturehtml",$hsHtmlSigniture)  
  11. }  
  12. if($UsrConfig.Dictionary.ContainsKey("signaturetext")){  
  13.     $UsrConfig.Dictionary["signaturetext"] = $stTextSig  
  14. }  
  15. else{  
  16.     $UsrConfig.Dictionary.Add("signaturetext",$stTextSig)  
  17. }  
  18. $UsrConfig.Update()  
Message Records Management

The MRM Tag configuration for a mailbox is also held within a FAI item (you shouldn't be modifying this setting via EWS) but it is useful if you are creating a script that is going to be stamping these tags on Folders or Items to be able to retrieve them via EWS. This is a sample of getting the MRM Policy and Archive Tags from the FAI items that is held in the Inbox

  1. $folderid= new-object Microsoft.Exchange.WebServices.Data.FolderId([Microsoft.Exchange.WebServices.Data.WellKnownFolderName]::Inbox,$MailboxName)     
  2. #Specify the Inbox folder where the FAI Item is  
  3. $UsrConfig = [Microsoft.Exchange.WebServices.Data.UserConfiguration]::Bind($service"MRM"$folderid, [Microsoft.Exchange.WebServices.Data.UserConfigurationProperties]::All)  
  4. $ConfXML = [System.Text.Encoding]::UTF8.GetString($UsrConfig.XmlData)    
  5. [XML]$ConfXML = $ConfXML    
  6. $ConfXML.UserConfiguration.Info.Data.PolicyTag  
  7. $ConfXML.UserConfiguration.Info.Data.ArchiveTag  
If you love working with Binary data than there is a lot more that can be done on the customization side using this operation to modify View Definitions etc these are very targeted configurations though and can be time consuming so I'm not going to cover those for now.

Popular posts from this blog

Testing and Sending email via SMTP using Opportunistic TLS and oAuth in Office365 with PowerShell

As well as EWS and Remote PowerShell (RPS) other mail protocols POP3, IMAP and SMTP have had OAuth authentication enabled in Exchange Online (Official announcement here ). A while ago I created  this script that used Opportunistic TLS to perform a Telnet style test against a SMTP server using SMTP AUTH. Now that oAuth authentication has been enabled in office365 I've updated this script to be able to use oAuth instead of SMTP Auth to test against Office365. I've also included a function to actually send a Message. Token Acquisition  To Send a Mail using oAuth you first need to get an Access token from Azure AD there are plenty of ways of doing this in PowerShell. You could use a library like MSAL or ADAL (just google your favoured method) or use a library less approach which I've included with this script . Whatever way you do this you need to make sure that your application registration  https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-

How to test SMTP using Opportunistic TLS with Powershell and grab the public certificate a SMTP server is using

Most email services these day employ Opportunistic TLS when trying to send Messages which means that wherever possible the Messages will be encrypted rather then the plain text legacy of SMTP.  This method was defined in RFC 3207 "SMTP Service Extension for Secure SMTP over Transport Layer Security" and  there's a quite a good explanation of Opportunistic TLS on Wikipedia  https://en.wikipedia.org/wiki/Opportunistic_TLS .  This is used for both Server to Server (eg MTA to MTA) and Client to server (Eg a Message client like Outlook which acts as a MSA) the later being generally Authenticated. Basically it allows you to have a normal plain text SMTP conversation that is then upgraded to TLS using the STARTTLS verb. Not all servers will support this verb so if its not supported then a message is just sent as Plain text. TLS relies on PKI certificates and the administrative issue s that come around certificate management like expired certificates which is why I wrote th

The MailboxConcurrency limit and using Batching in the Microsoft Graph API

If your getting an error such as Application is over its MailboxConcurrency limit while using the Microsoft Graph API this post may help you understand why. Background   The Mailbox  concurrency limit when your using the Graph API is 4 as per https://docs.microsoft.com/en-us/graph/throttling#outlook-service-limits . This is evaluated for each app ID and mailbox combination so this means you can have different apps running under the same credentials and the poor behavior of one won't cause the other to be throttled. If you compared that to EWS you could have up to 27 concurrent connections but they are shared across all apps on a first come first served basis. Batching Batching in the Graph API is a way of combining multiple requests into a single HTTP request. Batching in the Exchange Mail API's EWS and MAPI has been around for a long time and its common, for email Apps to process large numbers of smaller items for a variety of reasons.  Batching in the Graph is limited to a m
All sample scripts and source code is provided by for illustrative purposes only. All examples are untested in different environments and therefore, I cannot guarantee or imply reliability, serviceability, or function of these programs.

All code contained herein is provided to you "AS IS" without any warranties of any kind. The implied warranties of non-infringement, merchantability and fitness for a particular purpose are expressly disclaimed.