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