Veeam Backup for Microsoft Office 365 RESTful API: Exchange restores

Veeam Backup for Microsoft Office 365 RESTful API: Exchange restores

Based upon the entire organization backup job, we will dig deeper on how to perform restores for Exchange and more important the requirements to it.

IMPORTANT: To export Veeam Backup for Microsoft Office 365 entities to PST or MSG files, you must have a 64-bit version of Microsoft Outlook 2016, Microsoft Outlook 2013 or Microsoft Outlook 2010 installed on the computer running restore sessions.

Starting a restore session

Before we can actually restore an item (e-mail, calendar item,…), we need to start a restore session. We will leverage the organization ID and perform a POST request against “/v2/Organizations/{organizationID}/action“. This will start a Veeam Explorer in the background and return a restore session ID. The restore session ID will be used during the restore process.

To start the restore session, we will leverage the following JSON which starts the Veeam Explorer for Exchange.

{
  "explore": {
    "datetime": "2019.02.10",
    "type": "vex"
  }
}

The JSON requires an explore parameter which has an additional 2 parameters.

  • datetime: this is the date of the restore point which you want to use. It can be a specific day or even point to the second (for example: 2019.02.01 16:15:30)
  • type: this parameter can have 3 values (VEX, VESP or VEOD)

As we want to restore e-mails, we leverage the type VEX which is short for Veeam Explorer for Exchange.

This will start the restore session in the background and will result in a 201 response code stating the Veeam Explorer has started. The result contains a restore session ID which we will use in the next parts to perform restores.

Restore session started

Restore possibilities

With the restore session ID, we can now perform the restores as needed. We can restore multiple objects:

  • Complete mailboxes
  • Specific folders or items
  • Multiple folders or items at once

In the following examples, we will use a complete mailbox as a source. Before we can restore the mailbox, we need to get the mailbox ID. We can get this via “/v2/RestoreSessions/{restoreSessionID}/Organization/Mailboxes” where we replace the restore session ID. This will result in a list of available mailboxes. Select the mailbox you want to restore and copy the ID as it will be used in the following API requests.

Mailbox response

Restore to original location

Now that we have the mailbox ID and the restore session ID, we can start the actual restores. A restore is performed by making a POST call against “/v2/RestoreSessions/{restoreSessionID}/organization/mailboxes/{mailboxID}/action“. The JSON to restore to the original location is defined below, make sure you replace the values needed for the username and password accordingly.

{
  "restoretoOriginallocation":  {
    "userName": "niels.engelen@XXXX.onmicrosoft.com",
    "userPassword": "C00lpa$$word"
  }
}

Upon performing this request, you will get a 200 response code with additional information via the JSON response body.

  • failedFolderscount: number of folders failed to restore
  • createdItemsCount: number of items failed to restore
  • mergedItemsCount: number of items merged during the restore
  • failedItemsCount: number of items failed to restore
  • skippedItemsCount: number of items skipped during the restore
Full mailbox restore information

Export to PST file

We can export the full mailbox as well to a PST by posting the following JSON against “/v2/RestoreSessions/{restoreSessionID}/organization/mailboxes/{mailboxID}/action“.

{
  "exporttoPst":  {
    "contentKeywords": ""
  }
}

If you don’t have Outlook installed on the VBO server, you will get an error.

Outlook error

While a succesful restore will show another message

Stop the restore session

Once finished doing the restores, we can stop the restore session. To stop a session, perform a POST against “/v2/RestoreSessions/{restoreSessionID}/Action” with the following JSON.

{ "stop": null }

This will result in a 200 response stating the restore session was stopped successfully.

What’s next?

In the next part, we will take a look at restoring OneDrive for Business. You will learn how to find and restore an item (files and folders). We will perform a restore to the original location and export to the item as a ZIP file.

Missed a part?

Niels Engelen on GithubNiels Engelen on Twitter
Niels Engelen
Working as a Principal Analyst in Product Management for Veeam Software with an interest in anything virtual and cloud with a strong focus on AWS, Azure and Microsoft 365. He is also a VMware Certified Professional, a Veeam Certified Architect and gained the VMware vExpert award (2012-2022).
Comments are closed.