Skip to main content


Creating Retention Policies for Microsoft Teams

Often times your organization will require you to retain certain data whether it be email, documents, instant messages, etc. However, data retention is often a very tricky subject since some industry regulations may require you to retain content for a minimum period of time (i.e. Sarbanes-Oxley Act) while other content you may only want to retain for a very limited amount of time. Luckily Microsoft’s retention policies give you the best of both worlds by allowing you to scale your retention policies accordingly so you can ensure you’re remaining compliant with all industry regulations and policies. This blog will be part of a 3 part series where I’ll be breaking retention down into the following topics:

  1. What the heck is retention and how does it work within Teams? (this blog)
  2. Where is my Teams data stored?
  3. How do I start configuring retention policies in my environment?

Now that I’ve given you the rundown on how this blog series will be structured let’s start learning about retention!

How does Retention Work in Teams?

By now you’re probably aware that by default Teams conversations are persistent meaning they will be retained forever. This is why we introduce retention policies into the mix because not all data can or should be retained forever. Microsoft Teams breaks retention policies down into two main policy types:

  • Preservation: This will ensure your data is preserved for a given time period, despite any changes on the end-users side. This ensures data is kept in its original context and allows you to use this data for compliance reasons and within eDiscovery until that time expires. Upon the time expiration, your policy will then dictate how the data is treated. Whether this includes deleting the data or doing nothing.
  • Deletion: If retaining data for too long becomes a liability issue then you’ll want to consider this option. This policy type will ensure the data is deleted from all relevant storage within Microsoft Teams after a specified duration.

Note: Retention of private channel messages are not yet supported. However, the retention of files shared in a private channel are supported. 

The Principles of Retention

When using retention policies in your organization you’re more likely than not to have multiple retention policies in place. This will typically mean that content being marked for retention will have several of those policies applied to it, each with different actions (retaining vs deleting vs both) and different retention periods. This can become quite daunting but with Microsoft’s principles of retention, you can determine which retention policies take precedence over others while not having to worry about one retention policy setting overwriting another retention policy setting.

Diagram of the principles of retention

Image provided by:

Retention will always trump deletion

For example, let’s say I have one retention policy in place that deletes all of my Teams channel messages after 2 months (60 days).



Then let’s say I add an additional retention policy where I specify that I want to retain Teams channel messages for 1 year prior to deleting it.




This would then mean that after those 2 months have passed users would no longer see those channel messages within Teams. However, since retention wins over deletion you will continue to have access to the hidden conversations folder under the group mailbox until that 1-year mark hits before it is permanently deleted.

The longest retention period wins

Let’s use our last example where we had one retention policy in place that retains Teams channel messages for 60 days while another retains Teams channel messages for 1 year prior to deletion. In this circumstance, the 1-year retention policy would take precedence over the 60-day retention policy thus the Teams channel messages will be retained until the end of the longest retention period (1 year).

Explicit inclusions win over implicit inclusions

Let’s say we had a retention policy in place to delete Teams chat messages for Bob Smith after 90 days. We have another retention policy in place to delete chat messages for all Teams users after 60 days. In this circumstance since the retention policy of 90 days was set explicitly for Bob Smith, his chat messages would be retained for 90 days while everyone else would have their chats retained for 60 days.

Shortest deletion period wins

Let’s say the Teams channel messages have several policies that delete the content (with no retention). In this case, the policy with the shortest deletion period trumps those that have a longer deletion period.

Licensing Requirements

Unlike expiration and naming policies, retention policies don’t require an Azure AD P1 license. Instead, retention policies only require a minimum of an Office 365 E3 license.

What happens when someone deletes data during a retention period?

Let’s say you have a user that modifies/deletes either a chat or channel message (illustrated as path #1 below) within Teams while under a retention period. What happens to the data? The message will be copied to the SubstrateHolds folder (a hidden folder in every user or group mailbox). It is stored in the folder until the retention period expires. Once that retention period expires the data will be permanently deleted.

If the channel messages aren’t deleted during the retention period (illustrated as path #2 below) the message will be moved to the SubstrateHolds folder within one day after the retention period expires. The message will be deleted one day after it is moved to the SubstrateHolds folder.

Note: Messages in the SubstrateHolds folder are searchable within eDiscovery. However once the message is permanently deleted it won’t be searchable within eDiscovery. 

Diagram of retention flow for Teams chat and channel messages

Image provided by:

Things to Note

  1. As you may (or may not) know files in Teams are stored within SharePoint Online and OneDrive for Business. Specifically, files shared within a channel are stored within SharePoint Online. These files can be found in the Files tab at the top of each channel. On the other hand, files shared in private or group chats are stored in your OneDrive for Business folder and are only shared with people in that conversation. These would be found in the Files tab at the top of your chat. Yet if you have a retention policy that deletes a file referenced in a Team chat or channel message before the message itself is deleted then the file will still continue to show up in the Teams message. However, if you click on the file you’ll receive a “File not found” error. You could also potentially receive this error though if someone were to manually delete the file from SharePoint Online or OneDrive for Business with no retention policy in place.
  2. Teams chats and channel messages are not affected by retention policies applied to a user or group mailboxes in Exchange or O365 groups locations. Even though Teams chats and channel messages are stored in Exchange, they’re affected only by retention policies applied directly to the Teams location.
  3. If you try to delete a mailbox of a user that has an active retention policy in place that retains their Teams data, you will find that this won’t work. In order to delete the mailbox of that user, the admin will need to exclude the user from that retention policy first.
  4. Teams requires a separate retention policy. You’ll notice when you go to toggle on the Teams location, all other locations will be toggled off. In short, a retention policy that needs to include Teams can only include Teams locations. With that being said, if you created an org-wide policy Teams would not be included. Thus you would need to create a separate policy for Teams if you plan on retaining Teams data.
  5. Retention of Teams content can be as short as one day! However, it may take up to three days after the retention period expires before messages are permantently deleted.

For a full breakdown of all things retention, check out the official Microsoft documentation here. Join me next time when we discuss when we take a deeper look at where your data in Teams is stored! I hope you have found this blog helpful, and hope to see you all in the next blog!

Thoughts on “Creating Retention Policies for Microsoft Teams”

  1. Brian Siefferman Post author

    Hi Vaibhav,

    Thanks for bringing this to my attention. Not sure how I forgot to finish this blog series off, so I’ll put this on my “To-Do” list for my next blog. Thanks and happy to hear the blog was helpful!


Leave a Reply

Your email address will not be published. Required fields are marked *

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

Brian Siefferman

Brian is a Technical Consultant for Perficient’s Unified Communications practice focusing primarily on Skype for Business and Microsoft Teams workloads. He has been in this role since December 2017 and has an active presence blogging about all things Teams related. Currently, Brian resides in the suburbs of Chicago and enjoys running, swimming, weight lifting, and playing soccer in his free time.

More from this Author

Follow Us