PowerShell: Apply Retention Policies or Auto-Archive Settings to Inbox sub-folders

This week I’ve been spending some time in reviewing how Exchange Retention Policies and Outlook Auto-Archive setting are stored in a user mailbox.


If you’re wondering whether to start using Outlook Auto-Archive or the Exchange Retention policy I would like to call out some differences.


How important is enterprise data? If the answer to this question is “highly important” then this should be a no-brainer. Retention Policy in fact are applied from Exchange Admins and can be very granularly defined; also, the administrator can select what policies are made available to the user so to control the mailbox size. The data is moved from the “live” mailbox in Exchange to the “archive” mailbox, still in Exchange, this means that regardless where the data reside, you back-up plans can apply to the Archive Mailboxes ensuring enough data resiliency.

On top of that, should you not wish to use local storage, you can always rely on the Online Archive as part of the Office 365 offering. And most of all, the emails in the Archive mailbox will always be accessible from the most common clients (Outlook, OWA, EWS, REST) whilst you can still manipulate the archive mailbox via PowerShell.


If you are exploring the Outlook Auto-Archive feature, on the other hand, there are some downsides that need to be taken in account. The archival will be client-specific, meaning only the client where Auto-Archive is set up will be archiving content to a PST. This policy, unless enforced via GPO, is fully controlled by the end user and the PST would reside on a local drive, given network paths are not supported fro Outlook Data Files. This means that the data would only be accessible from that client where archiving has been enabled as it has got physical access to the PST file; in other words the archived content would not be accessible in OWA, other Outlook clients, EWS, REST, etc.

Most of all, this last option may expose the enterprise to data loss. Think about the hard drive where the PST is stored failing; the affected user may lose years worth of emails if the PST has not been backed up and, even if a back-up is available, there may still be few days of emails lost, if data was moved to the PST between the last back-up date and the date when the hard drive failed.


For the above reasons, I would suggest anyone to prefer the Exchange Retention Policies over the Outlook Auto-Archive feature.


Exchange Retention Policies.

The way these are surfaced, via EWS, is different between 2007/2010 and 2013/2016.

The main properties involved, set on each folder, are RetentionFlags, RetentionPeriod, RetentionTag, ArchivePeriod, ArchiveTag.

RetentionPeriod and RetentionTag are used to store Delete Policies information, these needs to be accesses as Extended MAPI properties via EWS, if the target endpoint is Exchange 2010 or earlier version; this is instead surfaced in Exchange 2013 and later version on the FirstClassProperty named PolicyTag.

Same applies to ArchivePeriod, ArchiveTag. These are used to stored Archive policy and again, these needs to be accessed via Extended MAPI on Exchange 2007/2010 while the same are exposed via the FirstClassProperty ArchiveTag on Exchange 2013/2016.

The last property, RetentionFlags, is used by the Managed Folder Assistant to discern which process needs to be performed. All the possible values are described on MSDN. If the ArchiveTag or the RetentionTag are modified on any subfolder it’s crucial to update the RetentionFlags otherwise the MFA would re-set the original policy value.


Outlook Auto-Archive Setting.

This setting is stored either on a group of Extended MAPI properties and/or on an Associated message whose class is IPC.MS.Outlook.AgingProperties.


The same properties, with the addition of PR_AGING_FILE_NAME (which contains the file location of the target PST) are stored in the hidden message.

My testing has focused on Outlook 2013 which, in my opinion, appears to solely leverage the IPC.MS.Outlook.AgingProperties associated message.


The Script.

The request behind the script was to be able to propagate the setting found on the Inbox to all its subfolders. This means that if a policy was set, that needed to be ported to the sub-folders (overwriting the existing one or creating a new one of none was present) or, alternatively, if none was set on the Inbox any policy on its sub-folders needed to be removed.

The sample shows how to retrieve, evaluate, overwrite or delete the properties listed above. The same includes a detailed help message and the solution embed a disclaimer.

The solution auto-detects the user PrimarySMTPAddress and the Credentials if none are provided; it’s anyway possible to provide an Administrator credential set and a target mailbox SMTP address if the admin has hot Full Access to the mailbox. Alternatively, if one or more mailboxes needs to be processed it is possible to assign the Administrator with Impersonation rights so that it can access all the mailboxes that need to be processed.


Some Samples.

The following samples relies on few variables to be pre-populated (as follows).

$Cred = Get-Credential
$EWSUrl = "https://mail.contoso.com/EWS/Exchange.asmx"
$TargetMailbox = "User@Contoso.com"


If you can’t be asked typing the credentials multiple times, should you be testing it multiple times, you can set the credentials as follows.

$Credential = New-Object System.Management.Automation.PSCredential -ArgumentList ('Administrator@Contoso.com'), (ConvertTo-SecureString -AsPlainText 'SomeStrongPassword' -Force)


First thing first: the help. This can be retrieved via PowerShell, invoking the command form the script location as demonstrated below as hopefully should address the most basic doubts.

Get-Help .\ApplyRetPolToSubfodlers.ps1
Get-Help .\ApplyRetPolToSubfodlers.ps1 -Examples
Get-Help .\ApplyRetPolToSubfodlers.ps1 -Detailed


Set the Outlook Auto-Archive settings found on the Inbox to all its subfolder, for a single mailbox. The credentials used are either the one of an Administrator who has Full Access on the target mailbox or are the actual user credentials (accessing the mailbox as self).

.\ApplyRetPolToSubfodlers.ps1 -Credentials $Cred -Mailbox $TargetMailbox -EwsUrl $EWSUrl -UpdateOutlookAutoArchive -LogFile .\Log.txt


Same as above now but, instead updating the Outlook Auto-Archive settings we are setting the Retention Policy (either Delete or Archive).

.\ApplyRetPolToSubfodlers.ps1 -Credentials $Cred -Mailbox $TargetMailbox -EwsUrl $EWSUrl -UpdateExchangeRetentionPolicy -LogFile .\Log.txt


Now, let’s use Impersonation to achieve the same goal. This applies to both the scenarios (-UpdateExchangeRetentionPolicy or -UpdateOutlookAutoArchive) so only one is demoed. The procedure to set this up is well documented on MSDN.

.\ApplyRetPolToSubfodlers.ps1 -Credentials $Cred -Mailbox $TargetMailbox -EwsUrl $EWSUrl -UpdateExchangeRetentionPolicy -Impersonate -LogFile .\Log.txt


Impersonation is extremely helpful when there are more than one mailbox that needs to undergo the above procedure. Again, as there is no major difference in the batch processing between the 2 functions, only one is showcased.

.\ApplyRetPolToSubfodlers.ps1 -Credentials $Credential -Mailbox .\MyUsers.csv -EwsUrl $EWSUrl -UpdateOutlookAutoArchive -Impersonate -LogFile .\Log.txt


As you can see, there is a reference to a generic .\MyUsers.csv. This, if you’re looking to follow this procedure, looks like the following.



Last note. If you need to run this script in a hybrid deployment, where mailboxes may reside in either the On-Premise environemtn or in Cloud, you need to omit the -EwsUrl parameter since the cloud and the local URL are different. Also, if your AutoDiscover record points to the On-Premise server, you need to leverage the -AllowInsecureRedirection switch as otherwise the AutoDiscover process would not be able to follow the redirection to cloud for the migrated mailboxes. Please note that to use impersonation against both forest you need to make sure the ApplicationImpersonation RBAC is set on both Exchange Organizations. Example follows.

.\ApplyRetPolToSubfodlers.ps1 -Credentials $Credential -Mailbox .\MyUsers.csv -UpdateExchangeRetentionPolicy -Impersonate -AllowInsecureRedirection -LogFile .\Log.txt


The Solution.

This relies on EWS Managed API and has been tested with version 2.2

The sample can be downloaded on: ApplyRetPolToSubfodlers.


Comments (1)

  1. Paul Lee says:

    Nice script! I was wondering if it is possible to set retention policies in some way such that my Global Mailbox policy deletes items older than say 60 days; however I want ONE particular folder to be exempt from the policy and have no retention at all.

Skip to main content