Auto‑Apply Retention Labels in Exchange Online by Keyword Query

Why Auto‑Apply Retention Labels Matter

When a compliance team needs to ensure that any message containing a sensitive keyword is automatically retained or deleted, a keyword‑based auto‑apply label is the most efficient solution. It eliminates the need for end‑users to remember to tag messages and guarantees that the policy is enforced on all future items.

Step‑by‑Step: Create an Auto‑Apply Label

All commands run in a PowerShell session that has been connected to the Microsoft 365 Compliance Center. Use the Connect-IPPSSession cmdlet or the newer Connect-ExchangeOnline with the -ShowBanner:$false switch.

# Connect to the compliance session (requires admin credentials)
Connect-IPPSSession

# 1. Create the label – retention action, duration, and enable it as a policy label
$label = New-RetentionComplianceLabel \
    -Name 'ConfidentialProject' \
    -RetentionAction 'Delete' \
    -RetentionDuration 3650 \
    -IsRetentionPolicy $true

# 2. Define the keyword rule. The query must be under 4 KB and use supported syntax.
$rule = New-RetentionComplianceRule \
    -Name 'ProjectKeywordRule' \
    -ContentMatchQuery '(project OR confidential) AND (sent:>=2024-01-01)'

# 3. Create the policy that contains the rule
$policy = New-RetentionCompliancePolicy \
    -Name 'ProjectRetentionPolicy' \
    -RetentionComplianceRule $rule.Name

# 4. Link the label to the policy and enable auto‑apply
Set-RetentionComplianceLabel \
    -Name $label.Name \
    -Policy $policy.Name \
    -IsAutoApplyEnabled $true

Key points in the script:

• -IsRetentionPolicy $true turns the label into a policy‑label that can be auto‑applied.
• The ContentMatchQuery uses the same syntax as the Microsoft 365 search box. Avoid leading wildcards (e.g., *text) and keep the query under 4 KB.
• Auto‑apply is only enabled on the label, not on the policy itself.

Key Limits and Common Pitfalls

• Tenant‑wide limit: 10 retention policies. Each policy may contain up to 50 rules.
• Keyword query size: ≤4 KB. Exceeding this causes the New-RetentionComplianceRule command to fail.
• Scope limitation: Auto‑apply works only on Exchange Online mailbox items (primary and archive if included). It does not affect public folders, SharePoint, or Teams chat unless explicitly scoped.
• Retention labels are not retroactive. Existing items are not tagged until the label is activated and the policy refreshes.
• Changing a keyword query after activation requires re‑applying the policy. Otherwise, the old query continues to govern matching items.

Verifying the Result

After executing the script, wait up to 7 days for the policy refresh cycle. Then confirm the label has been applied:

1. In the Security & Compliance Center, navigate to Label analytics and look for the ConfidentialProject label. The Auto‑Apply count should increase when a matching message arrives.
2. Alternatively, run PowerShell:

   Get-RetentionCompliancePolicy -Identity 'ProjectRetentionPolicy' | FL
   Get-RetentionComplianceLabel -Identity 'ConfidentialProject' | FL
   Get-RetentionComplianceRule -Identity 'ProjectKeywordRule' | Select-Object Name, ContentMatchQuery
   

3. Send a test email containing the keyword (e.g., "project update") to a user mailbox, then check the mailbox for the label under the item’s properties.

When It Won’t Work

• Forgot to set -IsAutoApplyEnabled $true on the label – the policy will still exist but the label won’t be applied automatically.
• Using an unsupported search operator (e.g., OR with parentheses incorrectly placed) will cause the rule creation to fail.
• Query size >4 KB – the command returns an error “ContentMatchQuery size exceeds the maximum allowed.”
• Policy not refreshed within 7 days – the label appears to be inactive; wait or force a refresh using Set-RetentionCompliancePolicy -Identity <policy> -IsEnabled $true and re‑enable.

By following the steps above and watching for the limits, you can reliably auto‑apply a retention label to any Exchange Online mailbox item that contains a specified keyword.