How to Use PowerShell to Remove Calendar Items from Exchange Online

Clearing Outlook Calendars

A user on the Microsoft Technical Community reported that a teacher’s calendar had become cluttered with events for classes. So much so that the number of events caused the Teams calendar app to crash. The request was for a way to clear calendar events for selected users for a set period.

The Exchange Online PowerShell module includes the Remove-CalendarEvents cmdlet. Unfortunately, this cmdlet is forward-looking and can only cancel future meetings in someone’s calendar. It cannot remove old calendar events, which is the problem faced here.

The solution is to search the affected mailboxes to find calendar events and delete them. Microsoft has deprecated the old Search-Mailbox cmdlet, but it’s still available and can be used, even if Microsoft won’t support it. I’ve used Search-Mailbox many times to find and remove items from mailboxes, so it could solve this problem.

A Script to Remove Items from Mailboxes

The script written to do the job (downloadable from GitHub) is quite straightforward and involves the following steps:

  1. Find the mailboxes to process. I used Get-ExoMailbox to look for mailboxes with a value in the CustomAttribute12 attribute. You could also use a CSV file to provide the input (if you do, make sure to include the UserPrincipalName and DisplayName of each mailbox.
  2. Use Search-Mailbox to run an estimate search against each mailbox. An estimate search tells us how many items match the search query without doing anything else. The result of the query is logged.
  3. Present the details of mailboxes with items matching the search and ask the user to proceed (Figure 1).
  4. If affirmative, run Search-Mailbox again to remove the matching items. This stage is the longest to complete.
Displaying the results of Search-Mailbox estimates for several mailboxes
Figure 1: Displaying the results of Search-Mailbox estimates for several mailboxes

Obviously, by changing the search query and target set of users, the same script could be used to remove mailbox items in different circumstances, such as deleting malware.

Test Query Thoroughly

Remember that Search-Mailbox is what’s called a destructive cmdlet: it can and will remove mailbox items if told to do so. For this reason, it’s wise to test the search query used to make sure that it finds the correct items. The query used in this script looks for calendar meeting items between two dates with an exclusion for Teams call data records (CDRs), which will be picked up if you simply look for meeting items.

Upgrading to use Content Searches

Even though it works, Microsoft would prefer that you don’t use Search-Mailbox. That’s an understandable stance, so the next thing to do is to update the script to use content searches to find and remove mailbox items. That’s another day’s work.

The Search-Mailbox cmdlet is covered in the companion volume of the Office 365 for IT Pros eBook. We’ll keep that text until Microsoft finally removes this useful cmdlet from Exchange Online

7 Replies to “How to Use PowerShell to Remove Calendar Items from Exchange Online”

      1. By August 5 2021: Search-Mailbox : The term ‘Search-Mailbox’ is not recognized as the name of a cmdlet

  1. Thanks for the article,

    I am facing a challenge with something related to this, I am able to achieve the above result with either compliance search or search-mailbox but my requirement is slightly different.

    I need to remove future appointments from hundreds of user’s mailboxes based on certain criteria ( I managed to create the query).

    in KQL, searchable properties for an email item ( which is the appointment in this case) are limited and do not include the start property which is the actual date of the meeting.

    Any hints ?

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.