Summary

Update-Folders.ps1 is a PowerShell script that uses EWS (requires the EWS Managed API) to update folders within a mailbox (note that this can also affect items in a mailbox, for example if a folder is deleted). It can be used for multiple folders, and automated against multiple mailboxes. The script handles throttling and so works against large Office 365 mailboxes. Note that OAuth is required for Office 365.

The below examples assume that the Azure AD application registration details have been stored in PowerShell variables e.g.

$Mailbox = "[email protected]"
$clientId = "Application Id"
$tenantId = "Tenant Id"
$secretKey = "Secret key" # App only auth
$redirectUrl = "http://localhost/" # Delegate auth

Example 1

.\Update-Folders.ps1 -Mailbox $Mailbox -FolderPath "WellKnownFolderName.Root" -ProcessSubfolders -ExcludedFolderPaths ("\ApplicationDataRoot", "\GraphStore", "\ExchangeSyncData", "\Recoverable Items", "\Top of Information Store\Contacts") -Office365 -CreatedAfter  ([DateTime]::Now.AddDays(-1)) -Purge -HardPurge -Delete -OAuth -OAuthTenantId $tenantId -OAuthClientId $clientId -OAuthRedirectUri $redirectUrl -WhatIf

The above will remove any folders found within the entire mailbox (starting from root) that were created within the last day. It excludes some system folders (more could/should be excluded, but I haven't gone through them in detail). The authenticating account used had ApplicationImpersonation rights to the mailbox being accessed. Note that the -WhatIf parameter prevents any actions actually being applied to the mailbox (but any folders that would be deleted/purged will be logged). The script logs on using delegate auth flow (user will be prompted to log in to their mailbox).

Example 2

.\Update-Folders.ps1 -Mailbox $mailbox -FolderPaths @("WellKnownFolderName.LocalFailures","WellKnownFolderName.ServerFailures") -Office365 -PropertiesMustMatch @{"0x36DA0102" = @([byte]0x01,0x04,0x00,0x00,0x10,0x00)} -AddFolderProperties @{"0x36DA0102" = "010408001000"; "0x36de0003" = 0x10000000 } -OAuth -OAuthTenantId $tenantId -OAuthClientId $clientId -OAuthSecretKey $secretKey -Impersonate

This checks for a specific value set for PR_EXTENDED_FOLDER_FLAGS on the LocalFailures or ServerFailures folder. If the property matches the passed value (which is incorrect for these folders), then it is modified to the correct value (and another property also written). This example shows how to deal with binary MAPI properties for both filtering and updating. It uses OAuth with the app-only flow to access the mailbox.

Example 3

.\Update-Folders.ps1 -Mailbox $Mailbox -FolderPaths @("WellKnownFolderName.MsgFolderRoot\Archive") -Office365 -AddFolderProperties @{"0x301D0003" = 1 } -OAuth -OAuthTenantId $tenantId -OAuthClientId $clientId -OAuthSecretKey $secretKey -Impersonate

This adds (or updates) PidTagRetentionFlags on the Top of Information Store\Archive folder and sets its value to 1. It uses OAuth with the app-only flow to access the mailbox.

Parameters

-Mailbox: Specifies the source mailbox (from which items will be moved/copied).

-Archive: When specified, the archive mailbox will be accessed (instead of the main mailbox).

-PublicFolders: If this switch is present, folder path is required and the path points to a public folder.

-FolderPaths: Folder(s) to process - if omitted, the mailbox message root folder (Top of Information Store) is assumed.

-ExcludedFolderPaths: Any folder specified will be excluded from processing.

-ProcessSubfolders: When specified, subfolders will also be processed.

-DoNotExcludeSubfolders: If this switch is set, only those folders that specifically match the exclusion list will be excluded (subfolders of excluded folders will still be processed).

-IncludeSearchFolders: If this switch is set, search folders will also be processed (by default they are excluded).

-Delete: Deletes the folder(s).

-Purge: Purges (empties) the folder(s). This parameter is required if you want to delete folders that have messages in them.

-HardPurge: Purges (empties) the folder(s). This switch will force a hard-delete of any items found in the folder (otherwise soft-delete is used). Can only be used with -Purge (both switches are required).

-NewDisplayName: Changes the display name of the folder(s).

-RemoveCharactersFromDisplayName: Any characters defined here will be removed from any folder names use an array of characters, e.g. @('.').

-FolderClass: Sets the class of the folder(s) to that specified (e.g. IPF.Note).

-RepairFolderClass: If specified, any folders that do not have an item class defined (i.e. it is empty) will have the item class set. If -FolderClass is specified, all blank folder are set to that - otherwise, the class is set to the same as the parent folder.

-AddFolderProperties: Adds the given properties (must be supplied as hash table @{}) to the folder(s).

-DeleteItemProperties: Deletes the given properties from the folder(s).

-CreatedAfter: Only processes folders created after this date.

-CreatedBefore: Only processes folders created after this date.

-PropertiesMustExist: [NOT YET IMPLEMENTED]If specified, only items that have values in the given properties will be updated.

-PropertiesMustMatch: [NOT YET IMPLEMENTED]If specified, only items that match the given values in the given properties will be updated. Properties must be supplied as a Dictionary @{""propId"" = ""value""}".

-Credential: Credentials used to authenticate with EWS (provided as PSCredential).

-OAuth: when specified, will use OAuth to access the mailbox (required for MFA enabled accounts) - this requires the ADAL dlls to be available.

-OAuthClientId: The application Id as registered in Azure AD. If not specified, a global registration will be used that supports delegated access only.

-OAuthRedirectUri: The redirect Uri of the Azure registered application.

-Impersonate: If set, ApplicationImpersonation is used to access the mailbox(es).

-EwsUrl: EWS Url (if omitted, and -Office365 not specified, then autodiscover is used).

-Office365: If set, requests are directed to Office 365 endpoint (overrides -EwsUrl).

-ForceTLS12: If specified, only TLS 1.2 connections will be negotiated.

-EWSManagedApiPath: Path to managed API (if omitted, a search of standard paths is performed).

-IgnoreSSLCertificate: If set, invalid SSL certificates will be ignored and the connection made regardless. Use with care, required for self-signed certificates.

-AllowInsecureRedirection: If set, insecure redirection will be allowed during AutoDiscover.

-LogFile: Logs script activity to the specified file.

-TraceFile: Write all EWS traffic (requests/responses/headers) to the specified file.

-WhatIf: If set, no changes will be made to the target mailbox (but actions that would be taken will be logged).