PowerShell module for searching and restoring items in Recoverable Items

A recent addition to the Exchange administrator’s arsenal in Exchange Online is the ability to search and restore items located in the Recoverable Items folder of a mailbox, via Get-RecoverableItems  and Restore-RecoverableItems .  (I don’t find that it is documented yet, so I can’t link to cmdlet references.)  It is available only for Exchange Online and has other constraints, so I wrote a module that adds support for Exchange on-premises and additional features:

Module Native cmdlets
Supports Exchange Online mailboxes Yes Yes
Supports Exchange on-premises mailboxes Yes No
Supports archive mailboxes Yes No
Search in Deleted Items folder No Yes
Search in Deletions folder Yes Yes
Search in Purges folder Yes No
Search filter can use retention tag Yes No
Restore to original folder Yes Yes
Restore all item types Yes No

To avoid naming conflicts, my cmdlets are Get-MailboxRecoverableItems  and Restore-MailboxRecoverableItems .  The EXO cmdlets use native access to the store and require you to have the Mailbox Import Export role assigned to use them.  My module uses EWS and requires either full access or the impersonation right.  (Include the UseImpersonation parameter when you want to use the latter.)  If using on-premises, you can omit the Credential  parameter to use your current credentials.  If using Exchange Online (or to use explicit credentials on-premises) you need to use the Credential parameter to provide a credential object.

My cmdlets replicate the behavior of the native cmdlets as much as possible, such as the property names and format of the output:

  • SourceFolder is where the item is currently located.
  • If the item is stamped with the MAPI property that contains information about the folder it was in when it was deleted, the “short” folder ID is displayed in LastParentFolderId.  (Otherwise, it will have no value.)  This is not the complete entry ID for the folder, but is what is stored in the property, hence why I am calling it short.  (To be restored to that folder, if it still exists, requires building the complete ID, which the cmdlet will take care of.)
  • LastParentPath is where the item will be put if you restore it.  (This is why I mentioned I am replicating the behavior of the native cmdlets, because I wouldn’t have named the property that.)  This path will be the original folder if the LastParentFolderId is populated and that folder still exists, as indicated by the value of OriginalFolderExists.  Otherwise, it will be the path to the default folder of the item’s class.

Because of a bug in EWS when translating folder entry IDs in the archive mailbox, items restored from the archive mailbox will always be put in the primary mailbox’s default folder for the item’s class.  OriginalFolderExists will never have a value for items in the archive mailbox because the translation bug makes it impossible to determine if the original folder still exists.

You can’t pipe the output of Get-MailboxRecoverableItems  to Restore-RecoverableItems  (nor can you do so with the native cmdlets).  The Restore cmdlet takes the same arguments as the Get cmdlet.  You can modify the search filter for the restore based on the output of Get-MailboxRecoverableItems , including specifying an item entry ID or folder entry ID, but the Get cmdlet is essentially the same as running the Restore cmdlet with the WhatIf  parameter.

The default is to search just the Deletions folder of Recoverable Items (named, confusingly, RecoverableItems), but you can optionally specify any or all of the Purges folder, the archive mailbox’s Deletions folder, and the archive mailbox’s Purges folder.  (The cmdlet will silently skip the request to search an archive mailbox if there isn’t one, allowing you to pipe multiple mailboxes to the cmdlet without regard for whether any or all have archives.)  There are no restrictions on which parameters you use for a search filter (aka, there are no parameter sets), but using some combinations won’t be of value.  For example, providing an entry ID negates any value of also specifying a subject.

You can then run Restore-MailboxRecoverableItems  with the parameters you want to restore any or all of the matching items:

  • RestoreToFolderId is the short folder ID where the item has been placed.
  • WasRestoredToOriginalFolder will be True if the original folder was known and still exists, False is the original folder was known but no longer exists or if the original folder was not known.
  • WasRestoredSuccessfully will be True if the item was actually moved to the folder listed in ReturnedToFilePath, or False if an error occurred.
  • ReturnedToFilePath is the folder path where the item can now be found.

You can set whether to use autodiscover and, if not, the EWS URL at the top of the module.  (You can also enable SCP lookup, if using autodiscover, by setting the property on line 41.)  There are comments throughout if you want to see what is being done and why.  Download the module below:

  RecoverableItems.psm1 (26.3 KiB)

2 thoughts on “PowerShell module for searching and restoring items in Recoverable Items

  1. Excellent script! Is there a certain format for the -FilterEndTime and -FilterStartTime? Those seem to not return any results for me; running without them does, but I need to narrow down the scope since I don’t need everything in the dumpster…long story short we had a retention tag go haywire and wipe mail from all mailboxes, which I gotta recover.

    Thanks!

  2. Thank you for bringing this to my attention. The issue isn’t about the date format but when performing a search with more than one restriction. (It works fine when you search for a start date, or an end date, or a subject.) This is because I didn’t properly account for the way PowerShell returns the object with the search filter collection. I have corrected this in the module.

Leave a Reply

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

*