PowerShell - Using Office 365 REST API to get Calendar Events

A couple of weeks ago I was looking at a way to find the Calendar Events of an Office365 shared mailbox using PowerShell. Unfortunately I was not able to find a way to accomplished this task using the O365 Cmdlets. (Let me know in the comments if you know how…)

Update 2016/04/19: Function updated to support PageResult parameter

So I turned to the PowerShell Community and posted tweet about it.

Quickly I got an answer from @Mjolinor and @Glenscales who sent me some great stuff by using REST API. Thanks again guys!!

This is the example Glen sent me:

Invoke-RestMethod `
    -Uri "https://outlook.office365.com/api/v1.0/users/[email protected]/calendarview?startDateTime=$(Get-Date)&endDateTime=$((Get-Date).AddDays(7))"`
    -Credential (Get-Credential) |
    foreach-object{ $_.Value }

This example shows how to list the calendar events for the next week. This is great and exactly what I needed, plus this run super fast compared to using the PowerShell module.

Of course you will need to have permissions on the specified mailbox.

Even though it show this as a CustomObject, the object type is Microsoft.OutlookServices.Event, see this MSDN page to find all the properties and methods available: https://msdn.microsoft.com/office/office365/APi/complex-types-for-mail-contacts-calendar#EventResource

My obvious next step was to create a function to handle different mailbox with different parameters such as startdatetime, enddatetime or alternative credentials. See at the end of this post.

But before we go there, let’s see how we can interact with Office 365 API.

How to interact with the Office 365 API

The MSDN documentation on how to use the Office365 API is very well done, clear and complete, you can take a look at it here: https://msdn.microsoft.com/en-us/office/office365/api/api-catalog

In our case, we are interested by the Outlook Calendar.

Using the Calendar API

In the Overview Page, you will find information on how to query this API. All Calendar API requests use the following root URL: https://outlook.office365.com/api/{version}/{user_context}

{user_context} is the current user, as Calendar API requests are always performed on behalf of the current user.

You can specify the user context in one of two ways:</b

• Current User: With the me shortcut: /api/v1.0/me

Invoke-RestMethod `
    -Uri "https://outlook.office365.com/api/v1.0/me" `
    -Credential $cred

• A Specific user: With the users/{upn} format to pass the UPN or a proxy address, such as:

Invoke-RestMethod `
    -Uri "https://outlook.office365.com/api/v1.0/users/[email protected]" `
    -Credential $cred

Get the Calendar Events

We can now retrieve the events using one the following:

• Against the primary calendar ../me/calendarview?startDateTime={ start_datetime }&endDateTime={ end_datetime }

Invoke-RestMethod `
    -Uri "https://outlook.office365.com/api/v1.0/me/calendarview?startDateTime=$(Get-Date)&endDateTime=$((Get-Date).AddDays(7))" `
    -Credential $cred |
ForEach-Object { $_.value } |
Select-Object -Property Subject

• Against a specific calendar ../me/calendars/{calendar_id}/calendarview?startDateTime={ start_datetime }&endDateTime={ end_datetime }

Invoke-RestMethod `
    -Uri "https://outlook.office365.com/api/v1.0/me/calendars/$id/calendarview?startDateTime=$(Get-Date)&endDateTime=$((Get-Date).AddDays(7))" `
    -Credential $cred |
ForEach-Object { $_.value } |
Select-Object -Property subject

Get the Calendars

The $ID variable in the above example can be retrieve using /Calendars This will list all the calendars present in the mailbox

Invoke-RestMethod `
    -Uri "https://outlook.office365.com/api/v1.0/me/calendars" `
    -Credential $cred | 
ForEach-Object { $_.Value } | 
Select-Object -Property Name, ID

PageResult

You can limit the number of item to output using the $top query parameter. If not specified only 10 items will be returned. You can specify up to 50 items to be returned.

This was implemented in the function below using the -PageResult parameter. For more information about the other filters available see the following page: https://msdn.microsoft.com/office/office365/APi/complex-types-for-mail-contacts-calendar#UseODataqueryparametersPageresults

Function Get-O365CalendarEvent

Finally, here is the function I built to query the calendar events. You can find it on my GitHub here: https://github.com/lazywinadmin/PowerShell/blob/master/O365-Get-O365CalendarEvent/O365-Get-O365CalendarEvent.ps1