How to Use PowerShell to Remove Calendar Items from Exchange Online

Clearing Outlook Calendars

A member of 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. What a great opportunity for the Search-Mailbox cmdlet, my go-to tool for mailbox cleanups for many years.

The Exchange Online management 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 use the Get-ExoMailbox cmdlet 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. The important thing is to create a set of mailboxes to process. For instance, a simple Get-ExoMailbox -RecipientTypeDetails UserMailbox will find all user mailboxes to process.
2. Call the Search-Mailbox cmdlet 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.

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 that you plan to use to remove items from multiple mailboxes to make sure that it finds the correct items. Create a test mailbox and populate it with different types of meetings to ensure that the search query finds the right items. Or if you’re really brave (or stupid), test the search and deletion against your own mailbox.

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 found and removed if the query looks only for meeting items. It’s a simple query that could be expanded to check against other message properties, such as the sender of the meeting invitation.

Upgrading to use Content Searches

Even though the cmdlet 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 because of the way that purge actions work for content searches. Where Search-Mailbox is happy to remove thousands of items from a mailbox, a content search is more restrained to make sure that a mistake in a search query doesn’t lead to a mass deletion in error.

---

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