Merge MailboxFolders.ps1 - David-Barrett-MS/PowerShell-EWS-Scripts GitHub Wiki

Summary

Merge-MailboxFolders.ps1 is a PowerShell script that uses EWS (requires the EWS Managed API) to merge folders within a mailbox and in some scenarios move folders and items between mailboxes. It can be used for multiple folders, and automated against multiple mailboxes. The script handles throttling and so works against large Office 365 mailboxes.

Version 1.2.8 and above work with both PowerShell 5 and PowerShell 7 (tested against 7.3.4). Earlier versions only work with PowerShell 5.

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

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

Examples

Restore Inbox items to primary mailbox from archive (EXO)

.\Merge-MailboxFolder.ps1 -SourceMailbox $SourceMailbox -SourceArchive -MergeFolderList @{"WellKnownFolderName.Inbox"= "Inbox"} -Office365 -OAuth -OAuthTenantId $tenantId -OAuthClientId $clientId -OAuthRedirectUri $redirectUrl

Note: Only the Inbox will be processed (no subfolders). Use -CreateTargetFolder -ProcessSubfolders to move the folder tree.

Move all Inbox items from primary mailbox to archive (EXO)

.\Merge-MailboxFolder.ps1 -SourceMailbox $SourceMailbox -TargetArchive -MergeFolderList @{"Inbox" = "WellKnownFolderName.Inbox"} -CreateTargetFolder -Office365 -OAuth -OAuthTenantId $tenantId -OAuthClientId $clientId -OAuthRedirectUri $redirectUrl

Move Inbox and subfolders from primary mailbox to archive (EXO)

.\Merge-MailboxFolder.ps1 -SourceMailbox $SourceMailbox -TargetArchive -MergeFolderList @{"Inbox"= "WellKnownFolderName.Inbox"} -ProcessSubfolders -CreateTargetFolder -Office365 -OAuth -OAuthTenantId $tenantId -OAuthClientId $clientId -OAuthRedirectUri $redirectUrl

Move Inbox and Sent Items (including subfolders) from primary mailbox to archive (EXO)

.\Merge-MailboxFolder.ps1 -SourceMailbox $SourceMailbox -TargetArchive -MergeFolderList @{"Inbox"= "WellKnownFolderName.Inbox"; "Sent Items"= "WellKnownFolderName.SentItems"} -ProcessSubfolders -CreateTargetFolder -Office365 -OAuth -OAuthTenantId $tenantId -OAuthClientId $clientId -OAuthRedirectUri $redirectUrl

Move Inbox and Sent Items (including subfolders) from archive mailbox to primary, with exclusions (EXO)

.\Merge-MailboxFolder.ps1 -SourceMailbox $SourceMailbox -SourceArchive -MergeFolderList @{"WellKnownFolderName.Inbox"= "Inbox"; "WellKnownFolderName.SentItems"= "Sent Items"} -ExcludeFolderList @("\Inbox\2018","\Inbox\2019") -ProcessSubfolders -CreateTargetFolder -Office365 -OAuth -OAuthTenantId $tenantId -OAuthClientId $clientId -OAuthRedirectUri $redirectUrl

Restore all items to primary mailbox from archive (Exchange on-premises)

.\Merge-MailboxFolder.ps1 -SourceMailbox $SourceMailbox -SourceArchive -ProcessSubfolders -CreateTargetFolder -Credential (Get-Credential) -EwsUrl "https://e1.e19.local/EWS/Exchange.asmx"

Note: the user will be prompted to enter the credentials to the mailbox.

Parameters

Parameters

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

-TargetMailbox: Specifies the target mailbox (if not specified, the source mailbox is also the target).

-SourcePublicFolders: Set this switch to access public folders instead of the user's primary mailbox as the data source.

-TargetPublicFolders: Set this switch to move items to public folders.

-MergeFolderList: Specifies the folder(s) to be merged. e.g. @{"WellKnownFolderName.Inbox" = "WellKnownFolderName.Inbox"}.

-ExcludeFolderList: Specifies the folder(s) to be excluded. Any folders that match the display name(s) will be ignored.

-PathsRelativeToMailboxRoot: If set, the folder paths are relative to the mailbox root. If this switch is not present, folder paths are assumed to be relative to message folder root (i.e. Top of Information Store).

-ExcludedMessageClasses: A list of message classes to be excluded from processing. Any items of these classes will be ignored.

-IncludedMessageClasses: A list of message classes to be processed. Any that don't match will be ignored.

-SearchFilter: If specified, only items that match the given AQS filter will be moved (see Perform an AQS search by using EWS in Exchange.

-OnlyItemsCreatedBefore: If specified, only items that were created before the specified date will be processed (useful for archiving).

-OnlyItemsSentReceivedBefore: If specified, only items that were sent or received before the specified date will be processed (useful for archiving).

-OnlyItemsCreatedAfter: If specified, only items that were created after the specified date will be processed (useful for archiving).

-OnlyItemsSentReceivedAfter: If specified, only items that were sent or received after the specified date will be processed (useful for archiving).

-OnlyItemsModifiedBefore: If specified, only items that were modified before the specified date will be processed.

-OnlyItemsModifiedAfter: If specified, only items that were modified after the specified date will be processed.

-ByFolderId: When specified, the folders in MergeFolderList are identified by EwsId (not path).

-ByEntryId: When specified, the folders in MergeFolderList are identified by EntryId (not path).

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

-CombineSubfolders: When specified, all items in subfolders of source will be moved to specified target folder (hierarchy will NOT be maintained).

-CreateTargetFolder: When specified, if the target folder doesn't exist, then it will be created (if possible).

-SourceArchive: When specified, the source mailbox being accessed will be the archive mailbox.

-TargetArchive: When specified, the target mailbox being accessed will be the archive mailbox.

-AssociatedItems: When specified, hidden (associated) items of the folder are processed (normal items are ignored).

-Delete: When specified, the source folder will be deleted after the move (can't be used with -Copy).

-Copy: When specified, items are copied rather than moved (can't be used with -Delete).

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

-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 (and will need consent to be able to access mailboxes).

-OAuthTenantId: The tenant Id in which the application is registered. If missing, application is assumed to be multi-tenant and the common log-in URL will be used.

-OAuthRedirectUri: The redirect Uri of the Azure registered application (defaults to http://localhost/code).

-OAuthSecretKey: Secret key to be used when obtaining access token. If this is specified, then application permissions are requested and no user log-on will be required.

-OAuthCertificate: The OAuth certificate to be used when obtaining access token. Application permissions are requested in this scenario. You can obtain a certificate from your own certificate store using the thumbprint: Get-Item Cert:\CurrentUser\My\50B510B4AE120D9B0EE3F059B6DD494469CD6D3B.

-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).

-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.

-VerboseLogFile: Logs verbose information to the specified file.

-DebugLogFile: Logs debug information to the specified file.

-FastFileLogging: If set, an optimised log file creator is used that should be signficantly faster (but may leave file lock applied if script is cancelled).

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

-BatchSize: Batch size (number of items batched into one EWS request) - this will be decreased if throttling is detected.

⚠️ **GitHub.com Fallback** ⚠️