How to Use New-Mailboxrestorerequest in Powershell

If you have ever managed multiple mailboxes inside an organization, then you know how problematic data restoration can be.

We often choose to delete useless or inactive mailboxes to have more control over the things that happen in a Microsoft 365 and Exchange environment, but what if we want to recover them later?

Today, we'll learn how to use New-MailboxRestoreRequest in PowerShell to recover valuable data, streamline mailbox moves, and ensure the integrity of your email communication.

What is the New-MailboxRestoreRequest Cmdlet?

The New-MailboxRestoreRequest cmdlet in PowerShell is used in Microsoft Exchange Server to initiate the process of restoring mailbox data.

This cmdlet is specifically used for mailbox restore operations and can only be found in on-premises Exchange and the cloud-based service.

The syntax of the New-MailboxRestoreRequest cmdlet is the following:

New-MailboxRestoreRequest

-SourceDatabase <DatabaseIdParameter>

-SourceStoreMailbox <StoreMailboxIdParameter>

-TargetMailbox <MailboxOrMailUserIdParameter>

[-AcceptLargeDataLoss]

[-AllowLegacyDNMismatch]

[-AssociatedMessagesCopyOption <FAICopyOption>]

[-BadItemLimit <Unlimited>]

[-BatchName <String>]

[-Confirm]

[-ConflictResolutionOption <ConflictResolutionOption>]

[-DomainController <Fqdn>]

[-ExcludeDumpster]

[-ExcludeFolders <String[]>]

[-IncludeFolders <String[]>]

[-MRSServer <Fqdn>]

[-Name <String>]

[-Priority <RequestPriority>]

[-SourceRootFolder <String>]

[-SuspendComment <String>]

[-Suspend]

[-TargetIsArchive]

[-TargetRootFolder <String>]

[-WhatIf]

[<CommonParameters>]

This is the meaning of the most important parameters of this command:

  • AcceptLargeDataLoss: Allows the restore operation to continue even if a large amount of data loss is expected.
  • AllowLegacyDNMismatch: Allows the restore operation even if there is a mismatch in Legacy Distinguished Names (DNs).
  • AssociatedMessagesCopyOption: Specifies options for copying associated messages during the restore.
  • BadItemLimit: Specifies the limit for the number of corrupted items allowed during the restore.
  • BatchName: Specifies a name for the restore batch.
  • Confirm: Prompts the user for confirmation before executing the command.
  • ConflictResolutionOption: Specifies options for resolving conflicts during the restore.
  • DomainController: Specifies the domain controller to use for this operation.
  • ExcludeDumpster: Excludes the Dumpster (recoverable items) during the restore.
  • ExcludeFolders: Excludes specific folders during the restore.
  • IncludeFolders: Includes specific folders during the restore.
  • MRSServer: Specifies the Mailbox Replication Service (MRS) server to use for the operation.
  • Name: Specifies a name for the restore request.
  • Priority: Specifies the priority of the restore request.
  • SourceRootFolder: Specifies the root folder in the source mailbox to restore.
  • SuspendComment: Adds a comment to the restore request when suspending.
  • Suspend: Suspends the restore request.
  • TargetIsArchive: Specifies that the target mailbox is an archive mailbox.
  • TargetRootFolder: Specifies the root folder in the target mailbox for the restore.

What Can You Use the New-MailboxRestoreRequest Command For?

Although the primary use of this cmdlet is to submit mailbox restore requests, the truth is that we are talking about a very useful command that can come in handy in the following situations:

  • Mailbox Data Recovery: Use New-MailboxRestoreRequest to recover mailbox data for a user from a backup or from a soft-deleted state in the source mailbox database. This can be useful in scenarios where a user's mailbox data is accidentally deleted or needs to be restored to a specific point in time;
  • Mailbox Moves and Merges: Facilitate mailbox moves or merges by restoring mailbox data to a different mailbox or database. This is particularly helpful when restructuring or consolidating mailbox databases;
  • Selective Item Recovery: Perform selective item recovery by using filters and options available in the cmdlet. You can exclude or include specific folders, keywords, or tags during the restore process, allowing for granular control over the recovered data;
  • Archived Mailbox Recovery: Restore data from an archived mailbox using the -IsArchive parameter. This enables the recovery of archived emails and other items associated with archive mailboxes;
  • Mailbox Decommissioning: As part of the mailbox decommissioning process, you can use New-MailboxRestoreRequest to retrieve and save mailbox data before permanently deleting the mailbox. This ensures that critical data is retained and can be accessed if needed.

Prerequisites to Run New-MailboxRestoreRequest

To run the New-MailboxRestoreRequest cmdlet, it's necessary to comply with certain requirements.

For example, users must have administrator permissions and the latest PowerShell version installed to continue with the process.

You can check out the exact permissions to run this cmdlet within your organization by running the following cmdlet:

$Perms = Get-ManagementRole -Cmdlet <Cmdlet>

In this case, you'll need to replace "cmdlet" with the cmdlet in question, so the command will look like this:

$Perms = Get-ManagementRole -Cmdlet New-MailboxRestoreRequest

The command will return the list of roles that can run this prompt. In case you are missing permissions, it'd be necessary to contact your administration's Exchange Online admins.

How to Use New-MailboxRestoreRequest in PowerShell

To use the New-MailboxRestoreRequest cmdlet, follow these quick three steps.

Step 1: Connect to Exchange Online PowerShell

First, connect to Exchange Online PowerShell using the following command:

Connect-ExchangeOnline -UserPrincipalName youremail@meetingroom365.com

Use your Microsoft credentials (with sufficient admin permissions) to log into the environment, and proceed to the following step.

Step 2: Use Get-MailboxStatistics to See Soft-Deleted Mailbox Information

According to Microsoft, since the mailbox in the source mailbox database is switched to a soft-deleted state when moved, you first need to get its information before restoring it from the recovery database.

In this case, the Get-MailboxStatistics cmdlet will help you see all the mailbox items and parameters so you can later retrieve them. For example:

Get-MailboxStatistics -Database MeetingRoom | Where {$_.DisconnectReason -eq "SoftDeleted" -or $_.DisconnectReason -eq "Disabled"} | Format-List LegacyExchangeDN,DisplayName,MailboxGUID, DisconnectReason

The aforementioned prompt will return the DisplayName, LegacyExchangeDN, and MailboxGUID (valid source mailbox identity values) for all mailboxes in the mailbox database named MeetingRoom that have a disconnect reason of SoftDeleted or Disabled.

This information is vital, as it would be impossible to successfully retrieve the info you need without the correct parameters.

Step 3: Run the New-MailboxRestoreRequest Command

Once you have all the email, mailbox, user, and file components needed, it's time to run the New-MailboxRestoreRequest cmdlet - let's take a look at an example:

New-MailboxRestoreRequest -SourceDatabase "MeetingRoom" -SourceStoreMailbox "James F" -TargetMailbox james@meetingroom365.com -TargetIsArchive

In this case, the cmdlet restores the content of the source mailbox with the DisplayName of James F on the mailbox database MeetingRoom to the archive mailbox for james@meetingroom365.com.

Remember that this cmdlet can be modified further to match your needs, which means that it's possible to retrieve more mailbox information if required.

Wrapping Up: How to Use the New-MailboxRestoreRequest Cmdlet in PowerShell

You now know how to use New-MailboxRestoreRequest, but before using the command, make sure to check out the following three key points:

  1. The New-MailboxRestoreRequest cmdlet can help organization administrators recover vital mailbox information, even if the mailboxes were soft-deleted in the past;
  2. Make sure to have sufficient permissions before attempting to use the cmdlet - otherwise, it will not work as expected;
  3. Some common issues with this cmdlet include the inability to retrieve the correct info due to a lack of data. Use the Get-MailboxStatistics command before running New-MailboxRestoreRequest to prevent certain PowerShell problems or bugs.