PowerShell: Merge mailbox folders 5/5 (1)


Note: I have removed the script download from this page, as maintaining it in two places seems unnecessary.  The new home for this script and any updates is here: https://code.msdn.microsoft.com/office/PowerShell-Merge-mailbox-e769c529.


A couple of years ago I wrote a script to move items from one folder to another in a user’s mailbox.  This seems to be one of the most commented posts on this blog, and we also regularly get requests for this kind of functionality.  I haven’t had a chance to respond to many of the comments of the previous post, however, I have recently rewritten this script with several enhancements.

To answer a couple of questions that do seem to crop up regularly… This script will not work to merge folders in different mailboxes.  While technically possible, updating the script to support merges between mailboxes would take some time, and we haven’t had much call for this as yet.  The script probably won’t work with public folder mailboxes, though it could be updated to do so and this shouldn’t be too complex (whether I get a chance to test this is another matter, though).

So, moving on to what the script does do…

The only required parameter for the script is MergeFolderList, which is the hash table listing the folders to be merged.  The easiest way to use the script when processing multiple folders is to define the hash table first of all.  For example:

$merge = @{
    “Inbox” = “Inbox2”;
    “Calendar” = @(“Kalendar”, “Agenda”);

As you can see, the hash table is a standard PowerShell hash table.  The key (the value on the left) is the primary folder (the folder into which all the items will be moved), while the value (on the right) is the secondary folder (all items will be moved out of this).  The value can be an array if you want to combine more than one folder – in the above example, all items from the folders Kalendar and Agenda will be moved into the Calendar folder.  Once you’ve set the $merge variable, you can call the script:

.\Merge-MailboxFolder.ps1 -MergeFolderList $merge

The above will process the current user’s mailbox.

By default, the script won’t delete the secondary folder once it has moved the items.  If you want to delete it, then just add the -delete parameter.  You can also create the target folder if it doesn’t exist by using the -CreateTargetFolder parameter.  As with previous scripts, you can also call it from an Exchange PowerShell console and use Get-Mailbox to process lots of mailboxes:

$m = Get-Mailbox
$m | ForEach-Object {
     .\Merge-MailboxFolder.ps1 –SourceMailbox $_.PrimarySmtpAddress -MergeFolderList $merge –Delete –Impersonate

You’ll need application impersonation permissions for the above (and it assumes that you are running the Exchange PowerShell console using the account that has been granted the impersonation permissions).

Script parameters:


 The source mailbox to be processed (if missing, current user’s mailbox is assumed, though this will only work in a domain environment).  If no target mailbox is specified, then the merge takes place within this mailbox.

 -TargetMailbox  The target mailbox – messages are moved/copied to this mailbox.
 -MergeFolderList  Specifies the folder(s) to be merged.
 -SearchFilter  If specified, only items that match the given AQS filter will be moved (see http://msdn.microsoft.com/EN-US/library/dn579420).
 -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, items in subfolders will all 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 archive is accessed (instead of the main mailbox).
 -TargetArchive  When specified, the target mailbox archive is accessed.
 -Delete  When specified, the source folder will be deleted after the merge (will only work if the source folder is empty).
 -Copy  When specified, items are copied (instead of moved) between folders.
 -Credentials  Credentials used to authenticate with EWS.
 -Username  Username used to authenticate with EWS.
 -Password  Password used to authenticate with EWS.
 -Domain  Domain used to authenticate with EWS.
 -Impersonate  Whether we are using impersonation to access the mailbox.
 -EwsUrl  EWS Url (if omitted, then autodiscover is used).
 -EwsManagedApiPath  Path to managed API (if omitted, a search of standard paths is performed).
 -IgnoreSSLCertificate  Whether to ignore any SSL errors (e.g. invalid certificate) – use with care.
 -AllowInsecureRedirection  Whether to allow insecure redirects when performing autodiscover.
 -LogFile  Log file – activity is logged to this file if specified.

Please rate this

Leave a Reply

Your email address will not be published. Required fields are marked *