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 2017/04/02: Support for timezone, Updated the function with error handler and some verbose messages. Added examples to retrieve the list of attendees emails

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

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

Any way to list calendar items of a shared mailbox using #PowerShell on #office365 (#Exchange Online) ? Can't find my answer so far

— François-Xavier Cat (@LazyWinAdm) April 30, 2015

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/sharedmailbox@domain.com/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:

• 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/fx.test10@lazywinadmin.com" -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

Extra: Retrieving the email of the attendees

As requested in comment, here is one way to retrieve the list of your attendees emails.

Get-O365CalendarEvent -EmailAddress info@lazywinadmin.com -Credential (Get-Credential) |
Select-Object -Property Subject,
                        StartTimeZone,
                        Start,
                        End,
                        @{ L = "Attendees"; E = { ($psitem.attendees.emailaddress | Select-Object -expand address) -join ',' } }

Thanks for reading! If you have any questions, leave a comment or send me an email at fxcat@lazywinadmin.com. I invite you to follow me on Twitter @lazywinadm / Google+ / LinkedIn. You can also follow the LazyWinAdmin Blog on Facebook Page and Google+ Page.