Restore SharePoint Recycle Bin Items with PnP PowerShell

#requires -Modules PnP.PowerShell

# Restore first-stage recycle bin items from selected folders
# deleted on one date, using CSOM paging to reduce threshold risk.

# Target SharePoint site where items were deleted.
$SiteUrl = "https://contoso.sharepoint.com/sites/Retail"

# Entra app Client ID used by PnP.PowerShell interactive authentication.
$ClientId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

# Folder paths without a leading slash.
$FolderPaths = @(
    "sites/Retail/Shared Documents/Folder1",
    "sites/Retail/Shared Documents/Folder2"
)

# Calendar date when the items were deleted.
$DeletedOnDate = Get-Date "05/20/2026"
$FromDate = $DeletedOnDate.Date
$ToDate = $DeletedOnDate.Date.AddDays(1).AddSeconds(-1)

# Leave blank to restore items deleted by any user.
$DeletedByEmail = ""

# Keep below 5000 to reduce threshold risk.
$PageSize = 1000

# Keep true until you have reviewed the CSV log.
$WhatIfMode = $true

# CSV log path for restored, skipped, and failed items.
$LogPath = "C:\Temp\RecycleBinRestoreLog_{0}.csv" -f (Get-Date -Format "yyyyMMdd_HHmmss")

Connect-PnPOnline -Url $SiteUrl -Interactive -ClientId $ClientId
$Context = Get-PnPContext

function Normalize-Path {
    param([Parameter(Mandatory = $true)][string]$Path)
    return $Path.Trim().TrimStart("/").TrimEnd("/")
}

function Test-ItemMatchesFolderPath {
    param(
        [Parameter(Mandatory = $true)]$RecycleBinItem,
        [Parameter(Mandatory = $true)][string[]]$NormalizedFolderPaths
    )

    $ItemDirName = Normalize-Path -Path $RecycleBinItem.DirName

    foreach ($FolderPath in $NormalizedFolderPaths) {
        if ($ItemDirName -like "$FolderPath*") {
            return $true
        }
    }

    return $false
}

function Test-OriginalItemExists {
    param([Parameter(Mandatory = $true)]$RecycleBinItem)

    $OriginalLocation = "/" + $RecycleBinItem.DirName.TrimStart("/") + "/" + $RecycleBinItem.LeafName

    try {
        if ($RecycleBinItem.ItemType -eq "File") {
            $ExistingFile = Get-PnPFile -Url $OriginalLocation -AsListItem -ErrorAction SilentlyContinue
            return ($null -ne $ExistingFile)
        }

        $ExistingFolder = Get-PnPFolder -Url $OriginalLocation -ErrorAction SilentlyContinue
        return ($null -ne $ExistingFolder)
    }
    catch {
        return $false
    }
}

function Get-NextPagingInfo {
    param([Parameter(Mandatory = $true)]$LastItem)

    try {
        $IdValue = [System.Uri]::EscapeDataString($LastItem.Id.ToString())
        $TitleValue = [System.Uri]::EscapeDataString($LastItem.Title)
        $SearchValue = [System.Uri]::EscapeDataString(
            $LastItem.DeletedDate.ToUniversalTime().ToString("yyyy-MM-ddTHH:mm:ssZ")
        )

        return "id=$IdValue&title=$TitleValue&searchValue=$SearchValue"
    }
    catch {
        return $null
    }
}

$NormalizedFolderPaths = $FolderPaths | ForEach-Object { Normalize-Path -Path $_ }
$Log = New-Object System.Collections.Generic.List[Object]

Write-Host "Site URL            : $SiteUrl" -ForegroundColor Cyan
Write-Host "Deleted date filter : $FromDate to $ToDate" -ForegroundColor Cyan
Write-Host "First-stage only    : Yes" -ForegroundColor Cyan
Write-Host "Page size           : $PageSize" -ForegroundColor Cyan
Write-Host "WhatIf mode         : $WhatIfMode" -ForegroundColor Cyan

$PagingInfo = $null
$PageNumber = 0
$TotalScanned = 0
$TotalMatched = 0
$TotalRestored = 0
$TotalSkipped = 0
$TotalFailed = 0
$ProcessedIds = @{}

do {
    $PageNumber++

    Write-Progress `
        -Activity "Scanning first-stage recycle bin" `
        -Status "Reading page $PageNumber. Total scanned: $TotalScanned" `
        -PercentComplete -1

    try {
        $RecycleBinItems = $Context.Web.GetRecycleBinItems(
            $PagingInfo,
            $PageSize,
            $false,
            [Microsoft.SharePoint.Client.RecycleBinOrderBy]::DeletedDate,
            [Microsoft.SharePoint.Client.RecycleBinItemState]::FirstStageRecycleBin
        )

        $Context.Load($RecycleBinItems)
        $Context.ExecuteQuery()
    }
    catch {
        Write-Host "Failed reading recycle bin page $PageNumber. Error: $($_.Exception.Message)" -ForegroundColor Red
        break
    }

    $CurrentPageItems = @($RecycleBinItems)
    $CurrentPageCount = $CurrentPageItems.Count

    if ($CurrentPageCount -eq 0) {
        break
    }

    $TotalScanned += $CurrentPageCount
    Write-Host "Page $PageNumber scanned. Items: $CurrentPageCount. Total scanned: $TotalScanned" -ForegroundColor DarkCyan

    $MatchingItems = $CurrentPageItems | Where-Object {
        $Item = $_

        if ($ProcessedIds.ContainsKey($Item.Id.ToString())) {
            return $false
        }

        $DateMatch = ($Item.DeletedDate -ge $FromDate -and $Item.DeletedDate -le $ToDate)
        $FolderMatch = Test-ItemMatchesFolderPath -RecycleBinItem $Item -NormalizedFolderPaths $NormalizedFolderPaths

        if ([string]::IsNullOrWhiteSpace($DeletedByEmail)) {
            $DeletedByMatch = $true
        }
        else {
            $DeletedByMatch = ($Item.DeletedByEmail -eq $DeletedByEmail)
        }

        return ($DateMatch -and $FolderMatch -and $DeletedByMatch)
    }
    $MatchingItems = $MatchingItems | Sort-Object `
        @{ Expression = { if ($_.ItemType -eq "Folder") { 0 } else { 1 } } }, `
        @{ Expression = { $_.DirName.Length } }, `
        DeletedDate

    foreach ($Item in $MatchingItems) {
        $ProcessedIds[$Item.Id.ToString()] = $true
        $TotalMatched++

        $OriginalLocation = "/" + $Item.DirName.TrimStart("/") + "/" + $Item.LeafName

        $LogEntry = [PSCustomObject]@{
            Id               = $Item.Id
            LeafName         = $Item.LeafName
            DirName          = $Item.DirName
            OriginalLocation = $OriginalLocation
            ItemType         = $Item.ItemType
            DeletedDate      = $Item.DeletedDate
            DeletedByEmail   = $Item.DeletedByEmail
            Action           = ""
            Status           = ""
            Error            = ""
        }

        try {
            $OriginalExists = Test-OriginalItemExists -RecycleBinItem $Item

            if ($OriginalExists) {
                $TotalSkipped++
                $LogEntry.Action = "Skipped"
                $LogEntry.Status = "Original item already exists"
                Write-Host "Skipped, item already exists: $OriginalLocation" -ForegroundColor Yellow
            }
            elseif ($WhatIfMode) {
                $TotalSkipped++
                $LogEntry.Action = "WhatIf"
                $LogEntry.Status = "Would restore"
                Write-Host "WhatIf: Would restore: $OriginalLocation" -ForegroundColor Cyan
            }
            else {
                $Item.Restore()
                $Context.ExecuteQuery()
                $TotalRestored++
                $LogEntry.Action = "Restored"
                $LogEntry.Status = "Success"
                Write-Host "Restored: $OriginalLocation" -ForegroundColor Green
            }
        }
        catch {
            $TotalFailed++
            $LogEntry.Action = "Failed"
            $LogEntry.Status = "Error"
            $LogEntry.Error = $_.Exception.Message
            Write-Host "Failed: $OriginalLocation. Error: $($_.Exception.Message)" -ForegroundColor Red
        }

        $Log.Add($LogEntry)
    }

    $LastItem = $CurrentPageItems[-1]
    $NewPagingInfo = Get-NextPagingInfo -LastItem $LastItem

    if ([string]::IsNullOrWhiteSpace($NewPagingInfo)) {
        Write-Host "No further paging information returned. Stopping scan." -ForegroundColor Yellow
        break
    }

    if ($NewPagingInfo -eq $PagingInfo) {
        Write-Host "Paging information did not change. Stopping to avoid a loop." -ForegroundColor Yellow
        break
    }

    $PagingInfo = $NewPagingInfo
}
while ($CurrentPageCount -eq $PageSize)

Write-Progress -Activity "Scanning first-stage recycle bin" -Completed

$LogDirectory = Split-Path -Path $LogPath -Parent
if (-not (Test-Path -Path $LogDirectory)) {
    New-Item -Path $LogDirectory -ItemType Directory -Force | Out-Null
}

$Log | Export-Csv -Path $LogPath -NoTypeInformation -Encoding UTF8

Write-Host ""
Write-Host "Completed." -ForegroundColor Cyan
Write-Host "Total scanned  : $TotalScanned" -ForegroundColor Cyan
Write-Host "Total matched  : $TotalMatched" -ForegroundColor Cyan
Write-Host "Total restored : $TotalRestored" -ForegroundColor Green
Write-Host "Total skipped  : $TotalSkipped" -ForegroundColor Yellow
Write-Host "Total failed   : $TotalFailed" -ForegroundColor Red
Write-Host "Log file       : $LogPath" -ForegroundColor Cyan