Set Up and Manage Retention Policies in Exchange Online with Windows PowerShell
Applies to: Office 365 for enterprises, Live@edu
For business, legal, or regulatory reasons, you may have to retain e-mail messages sent to and from users in your organization, or you may want to remove e-mail that you aren't required to retain. Messaging records management (MRM), the records management technology in Exchange Online, enables you to control how long to keep items in users' mailboxes and define what action to take on items that have reached a certain age.
- How MRM works in Exchange Online
- Retention settings in Exchange Online
- Manage MRM
- Before you begin
- Manage retention policies
- Manage retention tags
- Create a new retention policy
- Create a new retention tag
- Create a default policy tag (DPT) for voice mail messages
- Run the Managed Folder Assistant
- Next steps
How MRM works in Exchange Online
Retention policies and retention tags are part of the MRM technology. Retention policies use retention tags to apply retention settings to e-mail messages and folders. Retention tags define an age limit that specifies how long items are retained, and a retention action that specifies what happens to items that reach the retention age limit. Retention tags are linked to a retention policy, which is then applied to a mailbox.
.gif "Gg271153.d289533e-c1e6-4fea-8a44-90b699fac47d(en-us,EXCHSRVCS.149).gif")
Let's look closer at these components:
- Retention tags Retention tags define and apply retention settings to messages and folders in a user's mailbox. Retention tags specify how long a message is kept and the action taken when the message reaches the specified retention age. When a message reaches its retention age, it's moved to the user's archive mailbox or it's deleted. Retention tags are linked to a retention policy. There are three types of retention tags:
- Default policy tag (DPT) The settings defined in the DPT apply to all items in a mailbox that don't have a retention tag already applied. A retention policy can have up to three DPTs linked to it: one DPT with a retention action of Move to Archive, one DTP with a retention action of Delete and Allow Recovery, and one DTP for a specific message class, such as voice mail.
- Retention policy tags (RPT) RPTs are applied to default folders, such as Inbox, Sent Items, Deleted Items, and Junk Mail. An RPT takes precedence over a DPT.
Note RPTs don’t support a retention action that moves items to the user’s archive mailbox. The only retention action for RPTs is to delete items. - Personal tags Users can use Microsoft Outlook 2010 and Outlook Web App to apply personal tags to custom folders and individual items in their mailbox.
- Retention policies A retention policy is a group of retention tags that are applied to a mailbox. When a mailbox is created, a default retention policy is applied. In Exchange Online, the default retention policy applied to new mailboxes is named Default MRM Policy. A mailbox can have only one retention policy applied to it.
Note In Live@edu organizations, there are two default retention policies: MRMPolicy-DefaultMailboxPlan and MRMPolicy-GalDisabledMailboxPlan. - Retention tags are linked to a retention policy A retention policy can have two DPTs, each with a different retention action; one RPT for each default folder; and any number of personal tags.
How are retention policies processed?
The Managed Folder Assistant is a process that runs automatically in the Microsoft datacenters to process the retention settings that are applied to a mailbox. The Managed Folder Assistant applies the DPT and RPTs to the mailbox and makes personal tags available in Outlook 2010 and Outlook Web App so that users can apply them to custom folders or specific mailbox items. The Managed Folder Assistant processes the retention of items based on the tag type, retention age, and retention actions defined in each retention tag.
How often does the Managed Folder Assistant run? The Managed Folder Assistant is configured to process all mailboxes in a cloud-based organization in a specific span of time, which is known as a work cycle. In Exchange Online, the work cycle is seven days. This means that the assistant tries to process every mailbox in your cloud-based organization once every seven days.
Because the Managed Folder Assistant is running all the time, you don’t need to do anything to apply retention settings to mailboxes. However, if you need to apply retention settings to a mailbox immediately, you can force the Managed Folder Assistant to process a specific mailbox. See Run the Managed Folder Assistant.
Important MRM doesn’t guarantee retention of every message. For example, a user can delete or remove a message from their mailbox before the message reaches its retention age; MRM isn't designed to prevent users from deleting their own messages. If your organization requires retention of messages indefinitely, consider using one of these Exchange Online features:
- Journaling If your organization requires messages to be retained outside a user's mailbox for long-term storage, use journaling. See Journal Rules.
- Litigation hold If your organization has to preserve messages to meet e-discovery and retention requirements, you can put user mailboxes on litigation hold. See Put a Mailbox on Litigation Hold.
Also, single item recovery in Exchange Online lets you to recover a deleted e-mail message for up to 14 days after the message is permanently deleted by the user. See Recover Deleted E-Mail Messages in Exchange Online.
Top of page
Retention settings in Exchange Online
The following table shows the retention tags and their settings, which are available by default in Exchange Online for Microsoft Office 365 and Live@edu. All these tags are linked to the default retention policy that is applied to new mailboxes. That means these settings are applied to all new mailboxes.
When a personal retention tag is linked to the retention policy applied to a user's mailbox, the retention tag is automatically available to users to apply to their mailbox items.
| Tag name | Tag type | Retention age limit (days) | Retention action |
|---|---|---|---|
Default 2 year move to archive |
All (DPT)* |
730 |
Move to Archive |
Recoverable Items 14 days move to archive |
Recoverable Items** |
14 |
Move to Archive |
Deleted Items |
Deleted Items folder** |
30 |
Delete and Allow Recovery |
Junk Email |
JunkEmail** |
30 |
Delete and Allow Recovery |
Personal 1 year move to archive |
Personal |
365 |
Move to Archive |
Personal 5 year move to archive |
Personal |
1825 |
Move to Archive |
Personal never move to archive*** |
Personal |
No age limit |
Move to Archive |
1 Week Delete |
Personal |
7 |
Delete and Allow Recovery |
1 Month Delete |
Personal |
30 |
Delete and Allow Recovery |
6 Month Delete |
Personal |
180 |
Delete and Allow Recovery |
1 Year Delete |
Personal |
365 |
Delete and Allow Recovery |
5 Year Delete |
Personal |
1825 |
Delete and Allow Recovery |
Never Delete*** |
Personal |
No age limit |
Delete and Allow Recovery |
* Retention tags with a type of All are DPTs. DPTs apply to items that don't have another retention tag applied.
** The type for RPTs identifies the default mail folder that the tag applies to.
*** This tag isn't enabled by default. Items that have this retention tag are either never moved or never deleted.
Top of page
Manage MRM
As explained earlier, the settings from the default retention tags are automatically applied to every mailbox because a default retention policy is applied when mailboxes are created. However, if you want to change the retention behavior for your organization, you can use Windows PowerShell to manage retention policies and retention tags in Exchange Online.
Before you begin
To learn how to install and configure Windows PowerShell and connect to the service, see Use Windows PowerShell in Exchange Online.
Manage retention policies
| Task | Command |
|---|---|
Display a list of the retention policies available in your organization. |
|
Identify the retention policy applied to a mailbox. |
Example Run the following command to identify which retention policy is applied to Ian Tien's mailbox:
|
Apply a different retention policy to a mailbox. |
Example The following command applies the retention policy named Corp-Execs to Ian Tien's mailbox:
|
Remove the retention policy applied to a mailbox. |
|
Identify the retention tags linked to a retention policy. |
Example Here's a command to list the retention tags linked to the Default MRM Policy retention policy:
|
Add or remove a retention tag to a retention policy. |
Important When you add or remove a retention tag, be sure to include all the retention tags that you want to link to the retention policy. Why? The Set-RetentionPolicy cmdlet replaces the existing retention tags with the value you specify. Example Here's a command that adds the personal retention tag named "6 Month Delete" to the retention policy named Corp-Execs:
Tip Before you add or remove a retention tag, use the |
Top of page
Manage retention tags
| Task | Command |
|---|---|
Display a list of the retention tags available in your organization. |
Example Use the Get-RetentionPolicyTag cmdlet to display detailed information about retention tags. Run the following command to display the type, age limit, and retention action for all retention tags:
|
Change the retention age limit for a retention tag. |
Example Here's a command to increase the retention age limit for the Delete Items retention tag to 90 days:
|
Create a new retention policy
Use the New-RetentionPolicy cmdlet to create a new retention policy. Why create a new retention policy? For legal or regulatory reasons, you may have types of employees or entire departments that have different retention needs than the other people in your organization. You can create a new retention policy, link the appropriate retention tags, and then apply it to the appropriate mailboxes.
To create a new retention policy, run the following command:
New-RetentionPolicy <name>
To create a new retention policy and link retention tags to it, run the following command:
New-RetentionPolicy <name> -RetentionPolicyTagLinks <list of retention tags>
Example The following command creates a new retention policy named "Company Officers" and links two retention tags to it:
New-RetentionPolicy "Company Officers" -RetentionPolicyTagLinks "Company Officers-Deleted Items","Company Officers-Sent Items"
Top of page
Create a new retention tag
Use the New-RetentionPolicyTag cmdlet to create new retention tags. Just as you may need for a new retention policy for legal or regulatory reasons, you may have employees who require different retention periods or retention actions. You can create a new retention tag and then link it to new or existing retention policies.
To create a new retention tag, run the following command:
New-RetentionPolicyTag <name> -Type <type of tag> -AgeLimitForRetention <retention age limit, in days> -RetentionAction <action to take when retention age is met>
Example The following command creates a new retention tag named "Company Officers-SentItems." When applied to a mailbox, this retention tag deletes items in the Sent Items folder that are older than three months.
New-RetentionPolicyTag "Company Officers-SentItems" -Type SentItems -AgeLimitForRetention 90 -RetentionAction DeleteAndAllowRecovery
For more information about this cmdlet, see New-RetentionPolicyTag.
Note When creating new retention tags, you can only use the MoveToArchive action for retention tags of type All, Personal, and RecoverableItems.
Create a default policy tag (DPT) for voice mail messages
As previously mentioned, you can add one DPT for a specific message class to a retention policy. The following example creates a DPT for voice mail messages. When the tag is applied to a mailbox, voice mail messages that don't have a retention tag already applied are deleted after 14 days.
New-RetentionPolicyTag "Default voice mail 14 day delete" -Type All -MessageClass voicemail -Comment "Voice mail messages without a retention tag are deleted after 14 days." -AgeLimitForRetention 14 -RetentionAction DeleteAndAllowRecovery
To add this DPT to a retention policy, see Add or remove a retention tag to a retention policy.
Run the Managed Folder Assistant
As previously mentioned, the Managed Folder Assistant tries to process every mailbox in your cloud-based organization once every seven days. If you change a retention tag or apply a different retention policy to a mailbox, you can wait until the Managed Folder Assist processes the mailbox, or you can run the Start-ManagedFolderAssistant cmdlet to start the Managed Folder Assistant to process a specific mailbox. Running this cmdlet is useful for testing or troubleshooting a retention policy or retention tag settings.
The following command runs the Managed Folder Assistant for a specific mailbox:
Start-ManagedFolderAssistant -Identity <name of the mailbox>
Examples The following command starts retention processing on Ian Tien's mailbox:
Start-ManagedFolderAssistant -Identity "Ian Tien"
Top of page
Next steps
- Help users apply personal tags When a personal retention tag is linked to the retention policy applied to a user's mailbox, the tag is automatically available to users to apply to items in their mailbox. As explained earlier in this topic, users can use Outlook 2010 and Outlook Web App to apply personal retention tags to custom folders and individual items in their mailbox. Tell them how: Apply Retention Policies and Archive Policies to Your Messages.
- Put a mailbox on retention hold A retention hold suspends the retention policy applied to a mailbox. The result is that the Managed Folder Assistant doesn't process the retention settings or take retention actions. See Put a Mailbox on Retention Hold.