---

How to Search for Email Messages that have a Retention Tag in Office 365 Exchange Online

Introduction

This script searches for email messages that have a retention tag in Office 365 Exchange Online. This script returns email messages from multiple mailbox folders by default. You can use retention period rather than retention tag name to search.

Scenario

Currently, you can easily search email messages that have a retention tag in Outlook. But you wil find that this feature is not available in Outlook Web App (OWA). You want to find a workaround for those people who use Outlook Web App only.

Prerequisite

This script requires Exchange Web Service Managed API 2.0. Please download and install the package from Microsoft Download Center. This script cannot work correctly without this package.

Script

This script contains the following advanced functions:
·         Connect-OSCEXOWebService
·         Search-OSCEXOEmailMessage

 You can use this script in the following way.

1.        Open Windows PowerShell.
2.        Run Import-Module cmdlet to import this module file.
   Import-Module filepath\scriptname.psm1

Here are some code snippets for your reference.  

PowerShell
Edit|Remove
powershell
# Build search filter 
$verboseMsg = $Messages.BuildSearchFilter
$verboseMsg = $verboseMsg -f $RetentionPeriod.Count
$PSCmdlet.WriteVerbose($verboseMsg) 
$searchFilterCollection = New-Object Microsoft.Exchange.WebServices.Data.SearchFilter+SearchFilterCollection
 if ($RetentionPeriod -ne "*") {
    $searchFilterCollection.LogicalOperator = [Microsoft.Exchange.WebServices.Data.LogicalOperator]::Or
    foreach ($period in $RetentionPeriod) {
        $searchFilter = New-Object Microsoft.Exchange.WebServices.Data.SearchFilter+IsEqualTo(`
                        $exPropRetentionPeriod,$period)
        $searchFilterCollection.Add($searchFilter)
    }
} else {
        $searchFilter = New-Object Microsoft.Exchange.WebServices.Data.SearchFilter+Exists(`
                        $exPropRetentionPeriod)
        $searchFilterCollection.Add($searchFilter)
}

# Build search filter  
$verboseMsg = $Messages.BuildSearchFilter 
$verboseMsg = $verboseMsg -f $RetentionPeriod.Count 
$PSCmdlet.WriteVerbose($verboseMsg)  
$searchFilterCollection = New-Object Microsoft.Exchange.WebServices.Data.SearchFilter+SearchFilterCollection 
 if ($RetentionPeriod -ne "*") { 
    $searchFilterCollection.LogicalOperator = [Microsoft.Exchange.WebServices.Data.LogicalOperator]::Or 
    foreach ($period in $RetentionPeriod) { 
        $searchFilter = New-Object Microsoft.Exchange.WebServices.Data.SearchFilter+IsEqualTo(` 
                        $exPropRetentionPeriod,$period) 
        $searchFilterCollection.Add($searchFilter) 
    } 
} else { 
        $searchFilter = New-Object Microsoft.Exchange.WebServices.Data.SearchFilter+Exists(` 
                        $exPropRetentionPeriod) 
        $searchFilterCollection.Add($searchFilter) 
}



 

 

Examples

Example 1: How to display help about Search-OSCEXOEmailMessage.
To display help about this function, run this command.
Get-Help Search-OSCEXOEmailMessage -Full
 

Example 2: How to initiate a connection to Office 365 Exchange Online.
To initiate a connection to Office 365 Exchange Online, please run this command. You must run this example before any other steps.
Connect-OSCEXOWebService -Credential (Get-Credential admin@domain01.onmicrosoft.com)

Note The Connect-OSCEXOWebService function creates a new variable called exService. This variable is in the global scope of the current Windows PowerShell session. This variable is used by other functions in the script.

Example 3: How to return email messages that have 7 retention days or 1825 retention days applied.
To return email messages that have 7 retention days or 1825 retention days applied, please run this command.
Search-OSCEXOEmailMessage -RetentionPeriod "7","1825" | FT -AutoSize

Example 4: How to return email messages that have any retention tag(s) applied.
To return email messages that have any retention tag(s) applied, please run this command.
Search-OSCEXOEmailMessage -RetentionPeriod "*" | FT -AutoSize

Technical Resources:
Windows PowerShell Advanced Function
Creating search folders by using the EWS Managed API

Forum Threads:  

http://community.office365.com/en-us/forums/158/p/58186/212853.aspx
http://community.office365.com/en-us/forums/158/83379.aspx

 

 

 

Microsoft All-In-One Script Framework is an automation script sample library for IT Professionals. The key value that All-In-One Script Framework is trying to deliver is Scenario-Focused Script Samples driven by IT Pros' real-world pains and needs. The team is monitoring all TechNet forums, IT Pros' support calls to Microsoft, and script requests submitted to TechNet Script Repository. We collect frequently asked IT scenarios, and create script samples to automate the tasks and save some time for IT Pros. The team of All-In-One Script Framework sincerely hope that these customer-driven automation script samples can help our IT community in this script-centric move.