Summary

RecoverDeletedItems.ps1 is a PowerShell script that uses EWS (requires the EWS Managed API) to recover deleted items within a mailbox. Items can all be restored to a specified folder, or to the folder from which they were deleted (if that information is available).

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/code" # Delegate auth

For instructions setting up the Azure application, see Exchange Online OAuth Configuration.

Example 1

.\RecoverDeletedItems.ps1 -Mailbox $Mailbox -RestoreFromFolder "WellKnownFolderName.DeletedItems" -Office365 -OAuthTenantId $tenantId -OAuthClientId $clientId -OAuthRedirectUri $redirectUrl -WhatIf

The above will process all items in the Deleted Items folder (note that it won't process subfolders) and output which items it would recover to where (items are identified by Id). Remove -whatif to perform the restore.

Example 2

.\RecoverDeletedItems.ps1 -Mailbox $Mailbox -Archive -RestoreFromFolder "WellKnownFolderName.ArchiveRecoverableItemsDeletions" -Office365 -OAuthTenantId $tenantId -OAuthClientId $clientId -OAuthSecretKey $secretKey -WhatIf

The above will process all items in the RecoverableItems/Deletions folder of the archive mailbox and output which items it would recover to where (items are identified by Id). Remove -whatif to perform the restore.

Example 3

.\RecoverDeletedItems.ps1 -Mailbox $Mailbox -Archive -RestoreFromFolder "WellKnownFolderName.ArchiveRecoverableItemsDeletions" -RestorePolicyTag "fc92a703-51e3-411f-b850-4966668ee49c" -Office365 -OAuthTenantId $tenantId -OAuthClientId $clientId -OAuthSecretKey $secretKey -WhatIf

The above will process items in the RecoverableItems/Deletions folder of the archive mailbox and display which items it would recover to where (items are identified by Id). Only items that have a policy tag of the given GUID will be restored (GUID value is the RetentionId shown by Get-RetentionPolicyTag). Remove -whatif to perform the restore.

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

-RestoreStart: Start date (if items are older than this, they will be ignored).

-RestoreEnd: End date (if items are newer than this, they will be ignored).

-RestorePolicyTag: Policy tag of items to restore (only items with this tag will be restored).

-RestoreFromFolder: Folder to restore from (if not specified, items are recovered from retention). Use WellKnownFolderNames.DeletedItems to restore from Deleted Items folder.

-RecurseSubfolders: If specified, subfolders of the RestoreFromFolder will also be processed.

-RestoreToFolder: Folder to restore to if original location cannot be determined (if not specified, default folder will be chosen dependent upon item type).

-RestoreToFolderOverride: If specified, all items will be restored to folder specified in -RestoreToFolder (none will be restored to original location).

-SuppressDefaultFolderRestore: If specified, any items from folders that cannot be found will not be restored.

-RestoreToFolderDefaultItemType: If this is specified and the restore folder needs to be created, the default item type for the created folder will be as defined here. If missing, the default will be IPF.Note.

-IgnoreDrafts: If this is specified then any items marked as draft will be ignored.

-RestoreAsCopy: If this is specified then the item is copied back to the restore folder instead of being moved.

-RestoreMessageClasses: A list of message classes that will be recovered (any not listed will be ignored, unless the parameter is missing in which case all classes are restored).

-MyEmailAddress: If specified, any emails sent from this address will be considered as sent from the mailbox owner (can help with Sent Item matching).

-Exchange2007: If accessing Exchange 2007, different logic is needed to restore, so this switch must be specified.

-UseJunkRestoreFolder: If specified, and the PidLidSpamOriginalFolder property is set on the message, the script will attempt to restore to that folder.

-BatchSize: If more than one, move requests will be sent in batches of a maximum of this size. Defaults to 1, try 500 for large mailbox recovery.

-Credential: Credentials used to authenticate with EWS (provided as PSCredential). Note this will only work with Exchange on-premises.

-OAuth: when specified, will use OAuth to access the mailbox (required for Office 365 mailboxes). MSAL is required for certificate auth.

-OAuthClientId: The application Id as registered in Azure AD.

-OAuthTenantId: The tenant Id of the tenant being accessed.

-OAuthRedirectUri: The redirect Uri of the Azure registered application (required for delegate auth, but not app auth).

-OAuthSecretKey: If using application permissions, specify the secret key OR certificate.

-OAuthCertificate: If using application permissions, specify the secret key OR certificate.

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

-FastFileLogging: If selected, 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.

-WhatIf: If this switch is present, actions that would be taken will be logged, but nothing will be changed.