Public/Remove-MailboxExtendedProperty.ps1

function Remove-MailboxExtendedProperty {
    <#
    .SYNOPSIS
    Removes one explicitly selected MAPI extended property from matching mailbox items.

    .DESCRIPTION
    Removes only the requested extended-property definition from each supplied item. It never deletes the mailbox item. Every input is validated and guarded by ShouldProcess, then approved removals are sent to EWS in batches: one batched bind and one batched update per batch. Progress is updated after each batch. Use PassThru to return structured results. Properties already absent from an item are reported as successful. Conflicts, access failures, and validation failures are reported separately.

    Configure the EWS connection with Connect-EWSSession before removal. The command uses the configured session and its cached service for the target mailbox.

    .PARAMETER Identity
    Optional target mailbox SMTP address, alias, GUID, or another identifier resolvable by Get-Mailbox. If omitted, the mailbox is inferred from pipeline search results.

    .PARAMETER MailboxExtendedProperty
    Search-MailboxExtendedProperty results with ItemId and a typed property definition to remove.

    .PARAMETER BatchSize
    Maximum number of removal requests sent in one batched EWS bind/update request. All inputs are processed; larger input sets use multiple batches. Default 100.

    .PARAMETER RetryCount
    Maximum retries for transient EWS server-busy responses. Permanent validation, access, and change-key errors are not retried.

    .PARAMETER Verify
    Rebind each batch after update and confirm the properties are absent.

    .PARAMETER PassThru
    Return structured removal results including the originating search result, and display property identity and subject for actual removals.

    .EXAMPLE
    $matches | Remove-MailboxExtendedProperty -Identity user@contoso.com -WhatIf

    .EXAMPLE
    $matches | Remove-MailboxExtendedProperty -Identity user@contoso.com -Confirm
    #>

    [CmdletBinding(SupportsShouldProcess = $true, ConfirmImpact = 'High')]
    param(
        [Alias('MailboxIdentity', 'PrimarySmtpAddress')]
        [string]$Identity,

        [Parameter(Mandatory = $true, ValueFromPipeline = $true)]
        [Alias('SearchResult')]
        [psobject]$MailboxExtendedProperty,

        [ValidateRange(1, 1000)]
        [int]$BatchSize = 100,

        [ValidateRange(0, 10)]
        [int]$RetryCount,

        [switch]$Verify,

        [switch]$PassThru
    )

    begin {
        $totalCount = 0
        $mailboxCache = @{}
        $pendingEntries = New-Object 'System.Collections.Generic.List[object]'
        $removalCounts = @{ Removed = 0; AlreadyAbsent = 0; Skipped = 0; Failed = 0 }
        $progressActivity = 'Removing mailbox extended properties'
        if (-not $PSBoundParameters.ContainsKey('RetryCount')) {
            $RetryCount = if ($script:ConnectionOptions -and $script:ConnectionOptions.PSObject.Properties['RetryCount']) { [int]$script:ConnectionOptions.RetryCount } else { 3 }
        }
        function Get-RemovalErrorCode {
            param([string]$Message, [string]$ServiceErrorCode, [Exception]$Exception)

            $text = "$ServiceErrorCode $Message"
            if ($text -match '(?i)ErrorInvalidChangeKey|invalid change key|stale change key') { return 'StaleChangeKey' }
            if ($text -match '(?i)ErrorIrresolvableConflict|conflict') { return 'Conflict' }
            if ($text -match '(?i)ErrorAccessDenied|access denied|unauthorized') { return 'AccessDenied' }
            if ($Exception -is [System.ArgumentException]) { return 'ValidationError' }
            if ($Exception -is [System.InvalidOperationException]) { return 'MailboxMismatch' }
            if ($ServiceErrorCode) { return $ServiceErrorCode }
            if ($Exception) { return $Exception.GetType().Name }
            return 'Unknown'
        }

        function Set-RemovalFailure {
            param($Entry, [string]$ErrorCode, [string]$ErrorMessage)

            $Entry.Outcome = 'Failed'
            $Entry.Verified = $false
            $Entry.ErrorCode = $ErrorCode
            $Entry.ErrorMessage = $ErrorMessage
        }

        function New-RemovalResult {
            param($Entry)

            $removalCounts[$Entry.Outcome]++
            if (-not $PassThru) {
                if ($Entry.Outcome -eq 'Failed') {
                    Write-Warning ("Removal failed for item '{0}': {1}: {2}" -f $Entry.ItemId, $Entry.ErrorCode, $Entry.ErrorMessage)
                }
                return
            }
            if ($PassThru -and $Entry.Outcome -eq 'Removed') {
                Write-Host ('ExtendedPropertyId: {0} | Subject: {1}' -f $Entry.Definition.Identity, $Entry.Subject)
            }
            [pscustomobject]@{
                PSTypeName      = 'ExchangeNamedProperties.RemovalResult'
                MailboxIdentity = $Entry.MailboxIdentity
                ItemId          = $Entry.ItemId
                Subject         = $Entry.Subject
                FolderPath      = $Entry.FolderPath
                PropertySetId   = $Entry.PropertySetId
                PropertyId      = $Entry.PropertyId
                PropertyName    = if ($Entry.PropertyName) { $Entry.PropertyName } else { $null }
                PropertyType    = $Entry.PropertyType
                Action          = 'RemoveExtendedProperty'
                Succeeded       = $Entry.Outcome -in @('Removed', 'AlreadyAbsent')
                Verified        = $Entry.Verified
                ErrorCode       = $Entry.ErrorCode
                ErrorMessage    = $Entry.ErrorMessage
                Timestamp       = [DateTime]::UtcNow.ToString('o', [Globalization.CultureInfo]::InvariantCulture)
                Input           = if ($PassThru) { $Entry.Input } else { $null }
            }
        }

        function Write-RemovalProgress {
            param([int]$BatchNumber, [int]$BatchTotal)

            $processed = $removalCounts.Removed + $removalCounts.AlreadyAbsent + $removalCounts.Skipped + $removalCounts.Failed
            $percent = if ($totalCount -gt 0) { [int][Math]::Min(100, 100 * $processed / $totalCount) } else { 100 }
            $status = 'Batch {0} of {1} | Processed {2} of {3} | Removed {4} | Already absent {5} | Skipped {6} | Failed {7}' -f
            $BatchNumber, $BatchTotal, $processed, $totalCount,
            $removalCounts.Removed, $removalCounts.AlreadyAbsent, $removalCounts.Skipped, $removalCounts.Failed
            Write-Progress -Activity $progressActivity -Status $status -PercentComplete $percent
        }

        function Invoke-RemovalBatch {
            param($Service, [object[]]$Entries)

            # EWS item IDs are case-sensitive; group entries per item so each item is bound and updated once.
            $states = New-Object 'System.Collections.Generic.List[object]'
            $statesById = New-Object 'System.Collections.Generic.Dictionary[string,object]' ([StringComparer]::Ordinal)
            $ewsDefinitions = New-Object 'System.Collections.Generic.Dictionary[string,object]' ([StringComparer]::Ordinal)
            foreach ($entry in $Entries) {
                try {
                    $definitionKey = $entry.Definition.Identity
                    if (-not $ewsDefinitions.ContainsKey($definitionKey)) {
                        $ewsDefinitions[$definitionKey] = ConvertTo-EwsExtendedPropertyDefinition -Definition $entry.Definition
                    }
                    $entry.EwsDefinition = $ewsDefinitions[$definitionKey]
                    if (-not $statesById.ContainsKey($entry.ItemId)) {
                        $state = [pscustomobject]@{
                            ItemId        = $entry.ItemId
                            BoundItem     = $null
                            Entries       = New-Object 'System.Collections.Generic.List[object]'
                            Outcomes      = New-Object 'System.Collections.Generic.Dictionary[string,string]' ([StringComparer]::Ordinal)
                            UpdateFailure = $null
                        }
                        $statesById[$entry.ItemId] = $state
                        $states.Add($state)
                    }
                    $statesById[$entry.ItemId].Entries.Add($entry)
                }
                catch {
                    Set-RemovalFailure -Entry $entry -ErrorCode (Get-RemovalErrorCode -Message $_.Exception.Message -Exception $_.Exception) -ErrorMessage $_.Exception.Message
                }
            }

            if ($states.Count -gt 0) {
                $itemIds = @($states | ForEach-Object { $_.ItemId })
                $definitions = @($ewsDefinitions.Values)
                $boundStates = New-Object 'System.Collections.Generic.List[object]'
                try {
                    $bindResponses = @(Get-EwsItemBatch -Service $Service -ItemId $itemIds -PropertyDefinition $definitions -RetryCount $RetryCount)
                    for ($index = 0; $index -lt $states.Count; $index++) {
                        $state = $states[$index]
                        $response = if ($index -lt $bindResponses.Count) { $bindResponses[$index] } else { $null }
                        $itemProperty = if ($response) { $response.PSObject.Properties['Item'] } else { $null }
                        $boundItem = if ($itemProperty -and $itemProperty -isnot [System.Management.Automation.PSParameterizedProperty]) { $itemProperty.Value } else { $null }
                        if (-not $response -or [string]$response.Result -eq 'Error' -or -not $boundItem) {
                            $serviceErrorCode = if ($response) { [string]$response.ErrorCode } else { $null }
                            $message = if ($response -and $response.ErrorMessage) { [string]$response.ErrorMessage } elseif ($itemProperty -is [System.Management.Automation.PSParameterizedProperty]) { 'EWS returned an Item member that PowerShell could not resolve to an item object.' } else { 'EWS did not return the item.' }
                            foreach ($entry in $state.Entries) {
                                Set-RemovalFailure -Entry $entry -ErrorCode (Get-RemovalErrorCode -Message $message -ServiceErrorCode $serviceErrorCode) -ErrorMessage $message
                            }
                            continue
                        }
                        $state.BoundItem = $boundItem
                        $boundStates.Add($state)
                    }
                }
                catch {
                    $message = $_.Exception.Message
                    $code = Get-RemovalErrorCode -Message $message -Exception $_.Exception
                    foreach ($state in $states) {
                        foreach ($entry in $state.Entries) {
                            Set-RemovalFailure -Entry $entry -ErrorCode $code -ErrorMessage $message
                        }
                    }
                }

                $dirtyStates = New-Object 'System.Collections.Generic.List[object]'
                foreach ($state in $boundStates) {
                    foreach ($entry in $state.Entries) {
                        $definitionKey = $entry.Definition.Identity
                        if ($state.Outcomes.ContainsKey($definitionKey)) {
                            continue
                        }
                        $existingValue = $null
                        if ($state.BoundItem.TryGetProperty($entry.EwsDefinition, [ref]$existingValue)) {
                            [void]$state.BoundItem.RemoveExtendedProperty($entry.EwsDefinition)
                            $state.Outcomes[$definitionKey] = 'Removed'
                        }
                        else {
                            $state.Outcomes[$definitionKey] = 'AlreadyAbsent'
                        }
                    }
                    if ($state.Outcomes.Values -contains 'Removed') {
                        $dirtyStates.Add($state)
                    }
                }

                if ($dirtyStates.Count -gt 0) {
                    try {
                        $updateResponses = @(Update-EwsItemBatch -Service $Service -Item @($dirtyStates | ForEach-Object { $_.BoundItem }) -RetryCount $RetryCount)
                        for ($index = 0; $index -lt $dirtyStates.Count; $index++) {
                            $response = if ($index -lt $updateResponses.Count) { $updateResponses[$index] } else { $null }
                            if (-not $response -or [string]$response.Result -eq 'Error') {
                                $serviceErrorCode = if ($response) { [string]$response.ErrorCode } else { $null }
                                $message = if ($response -and $response.ErrorMessage) { [string]$response.ErrorMessage } else { 'EWS did not return an update response for the item.' }
                                $dirtyStates[$index].UpdateFailure = [pscustomobject]@{
                                    ErrorCode    = Get-RemovalErrorCode -Message $message -ServiceErrorCode $serviceErrorCode
                                    ErrorMessage = $message
                                }
                            }
                        }
                    }
                    catch {
                        $failure = [pscustomobject]@{
                            ErrorCode    = Get-RemovalErrorCode -Message $_.Exception.Message -Exception $_.Exception
                            ErrorMessage = $_.Exception.Message
                        }
                        foreach ($state in $dirtyStates) {
                            $state.UpdateFailure = $failure
                        }
                    }
                }

                foreach ($state in $boundStates) {
                    foreach ($entry in $state.Entries) {
                        $outcome = $state.Outcomes[$entry.Definition.Identity]
                        if ($outcome -eq 'Removed' -and $state.UpdateFailure) {
                            Set-RemovalFailure -Entry $entry -ErrorCode $state.UpdateFailure.ErrorCode -ErrorMessage $state.UpdateFailure.ErrorMessage
                        }
                        else {
                            $entry.Outcome = $outcome
                            $entry.Verified = $null
                        }
                    }
                }

                if ($Verify) {
                    $verifyStates = @($boundStates | Where-Object { @($_.Entries | Where-Object { $_.Outcome -ne 'Failed' }).Count -gt 0 })
                    if ($verifyStates.Count -gt 0) {
                        $verifyResponses = @()
                        $verifyFailure = $null
                        try {
                            $verifyResponses = @(Get-EwsItemBatch -Service $Service -ItemId @($verifyStates | ForEach-Object { $_.ItemId }) -PropertyDefinition $definitions -RetryCount $RetryCount)
                        }
                        catch {
                            $verifyFailure = "Verification bind failed: $($_.Exception.Message)"
                        }
                        for ($index = 0; $index -lt $verifyStates.Count; $index++) {
                            $state = $verifyStates[$index]
                            $response = if ($index -lt $verifyResponses.Count) { $verifyResponses[$index] } else { $null }
                            $itemProperty = if ($response) { $response.PSObject.Properties['Item'] } else { $null }
                            $verifiedItem = if ($itemProperty -and $itemProperty -isnot [System.Management.Automation.PSParameterizedProperty]) { $itemProperty.Value } else { $null }
                            foreach ($entry in @($state.Entries | Where-Object { $_.Outcome -ne 'Failed' })) {
                                if ($verifyFailure) {
                                    Set-RemovalFailure -Entry $entry -ErrorCode 'VerificationFailed' -ErrorMessage $verifyFailure
                                }
                                elseif (-not $response -or [string]$response.Result -eq 'Error' -or -not $verifiedItem) {
                                    $message = if ($response -and $response.ErrorMessage) { [string]$response.ErrorMessage } elseif ($itemProperty -is [System.Management.Automation.PSParameterizedProperty]) { 'EWS returned an Item member that PowerShell could not resolve to an item object.' } else { 'EWS did not return the item.' }
                                    Set-RemovalFailure -Entry $entry -ErrorCode 'VerificationFailed' -ErrorMessage "Verification bind failed: $message"
                                }
                                else {
                                    $remainingValue = $null
                                    if ($verifiedItem.TryGetProperty($entry.EwsDefinition, [ref]$remainingValue)) {
                                        Set-RemovalFailure -Entry $entry -ErrorCode 'VerificationFailed' -ErrorMessage 'The extended property is still present after the update.'
                                    }
                                    else {
                                        $entry.Verified = $true
                                    }
                                }
                            }
                        }
                    }
                }
            }

            foreach ($entry in $Entries) {
                New-RemovalResult -Entry $entry
            }
        }
    }

    process {
        $totalCount++
        $inputResult = $MailboxExtendedProperty
        $sourceAddress = if ($inputResult.PSObject.Properties['PrimarySmtpAddress']) { [string]$inputResult.PrimarySmtpAddress } else { $null }
        $sourceIdentity = if ($sourceAddress) { $sourceAddress } elseif ($inputResult.PSObject.Properties['MailboxIdentity']) { [string]$inputResult.MailboxIdentity } else { $null }
        $effectiveIdentity = if ($Identity) { $Identity } else { $sourceIdentity }
        $propertyDefinition = $inputResult
        $propertySetId = if ($propertyDefinition.PSObject.Properties['PropertySetId']) { [string]$propertyDefinition.PropertySetId } else { $null }
        if (-not $propertySetId -and $propertyDefinition.PSObject.Properties['PropertyNamespace']) {
            $propertySetId = [string]$propertyDefinition.PropertyNamespace
        }
        $propertyId = if ($propertyDefinition.PSObject.Properties['PropertyId']) { $propertyDefinition.PropertyId } elseif ($propertyDefinition.PSObject.Properties['PropDispId']) { $propertyDefinition.PropDispId } else { $null }

        $entry = [pscustomobject]@{
            Input           = $inputResult
            MailboxIdentity = $effectiveIdentity
            ServiceIdentity = $effectiveIdentity
            MailboxKey      = $null
            ItemId          = if ($inputResult.PSObject.Properties['ItemId']) { [string]$inputResult.ItemId } else { $null }
            Subject         = if ($inputResult.PSObject.Properties['Subject']) { [string]$inputResult.Subject } else { $null }
            FolderPath      = if ($inputResult.PSObject.Properties['FolderPath']) { [string]$inputResult.FolderPath } else { $null }
            PropertySetId   = $propertySetId
            PropertyId      = $propertyId
            PropertyName    = if ($propertyDefinition.PSObject.Properties['PropertyName']) { [string]$propertyDefinition.PropertyName } else { $null }
            PropertyType    = if ($propertyDefinition.PSObject.Properties['PropertyType']) { [string]$propertyDefinition.PropertyType } else { $null }
            Definition      = $null
            EwsDefinition   = $null
            Outcome         = $null
            Verified        = $false
            ErrorCode       = $null
            ErrorMessage    = $null
        }

        try {
            if ([string]::IsNullOrWhiteSpace($effectiveIdentity)) {
                throw [System.ArgumentException]::new('Identity is missing. Supply Identity or pipeline Search-MailboxExtendedProperty results that include MailboxIdentity or PrimarySmtpAddress.')
            }
            if (-not $mailboxCache.ContainsKey($effectiveIdentity)) {
                try {
                    $mailboxCache[$effectiveIdentity] = Resolve-MailboxIdentity -Identity $effectiveIdentity
                }
                catch {
                    $mailboxCache[$effectiveIdentity] = $_.Exception
                }
            }
            $targetMailbox = $mailboxCache[$effectiveIdentity]
            if ($targetMailbox -is [Exception]) {
                throw [System.ArgumentException]::new($targetMailbox.Message)
            }
            $entry.MailboxIdentity = $targetMailbox.Identity
            $entry.MailboxKey = $targetMailbox.PrimarySmtpAddress.ToLowerInvariant()

            if ([string]::IsNullOrWhiteSpace($entry.ItemId)) {
                throw [System.ArgumentException]::new('Input does not contain ItemId. Pipe Search-MailboxExtendedProperty results; Get-MailboxExtendedProperty inventory rows do not identify an item.')
            }
            if ($sourceAddress -and
                -not [string]::Equals($sourceAddress, $targetMailbox.PrimarySmtpAddress, [StringComparison]::OrdinalIgnoreCase)) {
                throw [System.InvalidOperationException]::new("Input item mailbox '$sourceAddress' does not match target mailbox '$($targetMailbox.PrimarySmtpAddress)'.")
            }
            if ([string]::IsNullOrWhiteSpace($entry.PropertyType)) {
                throw [System.ArgumentException]::new('The selected property definition has no PropertyType; supply a validated type before removal.')
            }
            if (([string]::IsNullOrWhiteSpace($entry.PropertyName) -and $null -eq $propertyId) -or
                (-not [string]::IsNullOrWhiteSpace($entry.PropertyName) -and $null -ne $propertyId)) {
                throw [System.ArgumentException]::new('The selected definition must contain exactly one of PropertyName or PropertyId.')
            }

            $entry.Definition = ConvertTo-NormalizedNamedProperty -Definition ([pscustomobject]@{
                    PropertySetId = $propertySetId
                    PropertyName  = $entry.PropertyName
                    PropertyId    = $propertyId
                    PropertyType  = $entry.PropertyType
                })
            if ($PSCmdlet.ShouldProcess("$($targetMailbox.PrimarySmtpAddress) item $($entry.ItemId)", "Remove extended property $($entry.Definition.Identity)")) {
                $pendingEntries.Add($entry)
            }
            else {
                $entry.Outcome = 'Skipped'
                $entry.ErrorCode = 'ShouldProcessDeclined'
                $entry.ErrorMessage = 'Removal was not approved.'
                New-RemovalResult -Entry $entry
            }
        }
        catch {
            Set-RemovalFailure -Entry $entry -ErrorCode (Get-RemovalErrorCode -Message $_.Exception.Message -Exception $_.Exception) -ErrorMessage $_.Exception.Message
            New-RemovalResult -Entry $entry
        }
    }

    end {
        if ($pendingEntries.Count -eq 0) {
            return
        }

        $mailboxKeys = New-Object 'System.Collections.Generic.List[string]'
        $entriesByMailbox = New-Object 'System.Collections.Generic.Dictionary[string,object]' ([StringComparer]::OrdinalIgnoreCase)
        foreach ($entry in $pendingEntries) {
            if (-not $entriesByMailbox.ContainsKey($entry.MailboxKey)) {
                $entriesByMailbox[$entry.MailboxKey] = New-Object 'System.Collections.Generic.List[object]'
                $mailboxKeys.Add($entry.MailboxKey)
            }
            $entriesByMailbox[$entry.MailboxKey].Add($entry)
        }
        $batchTotal = 0
        foreach ($mailboxKey in $mailboxKeys) {
            $batchTotal += [int][Math]::Ceiling($entriesByMailbox[$mailboxKey].Count / $BatchSize)
        }

        $batchNumber = 0
        Write-RemovalProgress -BatchNumber $batchNumber -BatchTotal $batchTotal
        try {
            foreach ($mailboxKey in $mailboxKeys) {
                $mailboxEntries = $entriesByMailbox[$mailboxKey]
                $service = $null
                $serviceFailure = $null
                try {
                    $service = Get-EwsService -Identity $mailboxEntries[0].ServiceIdentity
                }
                catch {
                    $serviceFailure = $_.Exception
                }

                for ($offset = 0; $offset -lt $mailboxEntries.Count; $offset += $BatchSize) {
                    $batchEntries = @($mailboxEntries.GetRange($offset, [Math]::Min($BatchSize, $mailboxEntries.Count - $offset)))
                    $batchNumber++
                    if ($serviceFailure) {
                        $code = Get-RemovalErrorCode -Message $serviceFailure.Message -Exception $serviceFailure
                        foreach ($entry in $batchEntries) {
                            Set-RemovalFailure -Entry $entry -ErrorCode $code -ErrorMessage $serviceFailure.Message
                            New-RemovalResult -Entry $entry
                        }
                    }
                    else {
                        Invoke-RemovalBatch -Service $service -Entries $batchEntries
                    }
                    Write-RemovalProgress -BatchNumber $batchNumber -BatchTotal $batchTotal
                }
            }
        }
        finally {
            Write-Progress -Activity $progressActivity -Completed
        }
    }
}