How to Use Get-MailboxRestoreRequest in Powershell

Mailbox management within a Microsoft Exchange Server is a task that requires a strong command of the tools available at hand.

If you are looking to perform mailbox restore operations but are unsure whether the target mailbox has already been scheduled for restoration or not, then allow PowerShell cmdlets to help you out.

In today's quick guide, we'll show you three steps to learn how to use Get-MailboxRestoreRequest in PowerShell.

What is the Get-MailboxRestoreRequest Cmdlet?

In Microsoft Exchange Server, the Get-MailboxRestoreRequest cmdlet is used in PowerShell to retrieve information about mailbox restore requests.

This cmdlet is part of the Exchange Management Shell (only available in on-premises Exchange and in the cloud-based service), and is typically used in scenarios where administrators need to restore or recover mailboxes.

This is the syntax of the Get-MailboxRestoreRequest command:

Get-MailboxRestoreRequest

[-BatchName <String>]

[-HighPriority <Boolean>]

[-Name <String>]

[-RequestQueue <DatabaseIdParameter>]

[-SourceDatabase <DatabaseIdParameter>]

[-Status <RequestStatus>]

[-Suspend <Boolean>]

[-TargetDatabase <DatabaseIdParameter>]

[-TargetMailbox <MailboxOrMailUserIdParameter>]

[-DomainController <Fqdn>]

[-ResultSize <Unlimited>]

[<CommonParameters>]

Let's quickly check out the meanings of the most important parameters of this syntax:

  • BatchName: Specifies the name of the mailbox restore batch. This parameter allows you to filter restore requests based on a specific batch name.
  • HighPriority: Indicates whether to prioritize mailbox restore requests with high priority. When set to $true, the cmdlet retrieves high-priority restore requests.
  • Name: Specifies the name of the mailbox restore request. You can use this parameter to filter and retrieve information about a specific restore request by name.
  • RequestQueue: Filters restore requests based on the source database's queue. It allows administrators to focus on restore requests from a specific source database queue.
  • SourceDatabase: Filters restore requests based on the source database. Use this parameter to narrow down results for restore requests originating from a specific source database.
  • Status: Filters restore requests based on their status (e.g., InProgress, Completed, Failed). This parameter helps administrators to view restore requests based on their current state.
  • Suspend: Specifies whether to include or exclude suspended restore requests. When set to $true, the cmdlet includes suspended requests.
  • TargetDatabase: Filters restore requests based on the target database. Use this parameter to focus on restore requests directed to a specific target database.
  • TargetMailbox: Filters restore requests based on the target mailbox. This parameter allows administrators to retrieve information about restore requests specific to a particular target mailbox.
  • DomainController: Specifies the fully qualified domain name (FQDN) of the domain controller to use. It helps control which domain controller the cmdlet interacts with.
  • ResultSize: Shows the maximum number of results to return. The Unlimited value indicates that there is no limit on the number of results.

What Can You Use the Get-MailboxRestoreRequest Command For?

The purpose of the Get-MailboxRestoreRequest command is to see the recovery status of soft-deleted or disconnected mailboxes. After running this command, administrators can use it for the following purposes:

  • Monitor Mailbox Restore Progress: Use Get-MailboxRestoreRequest to regularly check and track the status and progress of ongoing mailbox restore requests. This ensures that administrators stay informed about the real-time advancements in the restoration process, allowing for effective monitoring and intervention if necessary.
  • View Completed Restore Requests: Employ the cmdlet to retrieve comprehensive details about mailbox restore requests that have been successfully completed. This capability serves as a valuable auditing tool, providing insights into the history of restore activities for mailboxes within the Exchange Server environment.
  • Identify Failed Restore Attempts: Leverage Get-MailboxRestoreRequest to specifically target and isolate any failed mailbox restore requests. This functionality aids administrators in promptly identifying issues or errors that may have occurred during the restoration process, facilitating quick resolution and preventing potential data loss.

Prerequisites to Run Get-MailboxRestoreRequest in PowerShell

Checking the recovery status of primary mailboxes within a company is a task that only administrators are allowed to do.

Therefore, before running the Get-MailboxRestoreRequest cmdlet in PowerShell, first run the following command:

$Perms = Get-ManagementRole -Cmdlet <Cmdlet>

Replace the <cmdlet> part with Get-MailboxRestoreRequest like this:

$Perms = Get-ManagementRole -Cmdlet Get-MailboxRestoreRequest

The output will show you the required permissions and roles needed to run this command; if you need more permissions, make sure to contact your organization's support team or administrators.

How to Use Get-MailboxRestoreRequest in PowerShell

In order to use Get-MailboxRestoreRequest in PowerShell, we need to complete three quick steps.

Step 1: Connect to Exchange Online PowerShell

First of all, connect to Exchange Online PowerShell by opening PowerShell on your computer and running the following cmdlet:

Connect-ExchangeOnline -UserPrincipalName youremail@meetingroom365.com

Log into your account using your Microsoft credentials (email address and password), and proceed with the next step.

The Get-MailboxRestoreRequest command can be used after running the New-MailboxRestoreRequest cmdlet, which starts a restore request of mailbox items, information, and vital data.

As mentioned by Microsoft, soft-deleted mailboxes (and disabled mailboxes) do not entirely delete, but they enter into the recovery database, allowing for their recovery.

After placing mailbox restore requests with the New-MailboxRestoreRequest command, you can later see all the ongoing requests in the mailbox database with Get-MailboxRestoreRequest.

Step 2: Use Get-MailboxStatistics Cmdlet

Although running the Get-MailboxStatistics cmdlet is optional, we highly recommend you do it to make sure you have all the required information about the source mailbox.

The Get-MailboxStatistics command helps us retrieve information about company and user mailboxes that are now considered recoverable items.

Run Get-MailboxStatistics to get this information, which will help you prevent potential PowerShell errors.

Step 3: Run the Get-MailboxRestoreRequest Command

Now, it's time to run the command to retrieve the information you are looking for. Take a look at the following example:

Get-MailboxRestoreRequest -Identity "James\MailboxRestore"

In this case, the cmdlet returns the status of the in-progress and queued restore request with the identity James\MailboxRestore.

Now, if you want to check the status of restored mailboxes in databases, you can do this:

Get-MailboxRestoreRequest -TargetDatabase MeetingRoom365

This command will show the status of in-progress and queued restore requests that are being restored to the target database MeetingRoom365.

Finally, if you need to see restore requests that have been then suspended, you can use the following command example:

Get-MailboxRestoreRequest -Name "RestoreToMeetingRoom365" -Suspend $true

Wrapping Up: Using Get-MailboxRestoreRequest in PowerShell

Using the Get-MailboxRestoreRequest command is a great way to obtain the information you need for mailbox management. Before using this cmdlet, consider the following three points:

  • Get-MailboxRestoreRequest empowers users with the ability to gain real-time insights into the status, progress, and details of mailbox recovery tasks, thereby enhancing overall mailbox management efficiency within Microsoft Exchange Server.
  • By having the correct mailbox information, streamlining troubleshooting processes becomes easier. Administrators can leverage this cmdlet to quickly identify and address issues, ensuring a smoother and more controlled restoration experience.
  • Although the cmdlet works smoothly in most cases, it's important to be aware of common issues such as connectivity issues, insufficient permissions, or errors related to source and target databases.