Easy find mail folder and messages.ps1

function Find-MailFolderByName {
    [CmdletBinding()]
    param(
        [Parameter(Mandatory, Position=0, ValueFromPipelineByPropertyName)]
        [string][ValidateNotNullOrEmpty()]$UserPrincipalName,

        [Parameter(Mandatory, Position=1)]
        [string][ValidateNotNullOrEmpty()]$FolderName
    )

    begin {
        if (-not (Get-Module -ListAvailable -Name Microsoft.Entra.Users)) {
            throw "Microsoft.Graph.Users module not found. Please install with Install-Module Microsoft.Graph.Users."
        }
        Import-Module Microsoft.Entra.Users -ErrorAction Stop
    }

    process {
        try {
            if (-not (Get-EntraContext)) {
                Connect-Entra #-Scopes "Mail.Read"
            }
        } catch {
            throw "Failed to connect to Microsoft Graph: $_"
        }

        function Search-Folders {
            param(
                [string]$UserPrincipalName,
                [string]$FolderName,
                [string]$ParentFolderId = $null
            )

            $folders = if (-not $ParentFolderId) {
                (Invoke-MgGraphRequest -Method Get -Uri "https://graph.microsoft.com/v1.0/users/$UserPrincipalName/mailFolders" -OutputType PSObject).value
                #Get-MgUserMailFolderDelta -UserId $UserPrincipalName -All
            } else {
                (Invoke-MgGraphRequest -Method Get -Uri "https://graph.microsoft.com/v1.0/users/$UserPrincipalName/mailFolders/$ParentFolderId/childFolders" -OutputType PSObject).value
                #Get-MgUserMailFolderChildFolderDelta -UserId $UserPrincipalName -MailFolderId $ParentFolderId -All
            }

            foreach ($folder in $folders) {
                if ($folder.DisplayName -eq $null) { continue }
                if ($folder.DisplayName.Equals($FolderName, "InvariantCultureIgnoreCase")) {
                    # Add UPN property to folder object before returning
                    $folder | Add-Member -MemberType NoteProperty -Name UserPrincipalName -Value $UserPrincipalName -Force
                    return $folder
                }
                if ($folder.ChildFolderCount -gt 0) {
                    $result = Search-Folders -UserPrincipalName $UserPrincipalName -FolderName $FolderName -ParentFolderId $folder.Id
                    if ($result) { return $result }
                }
            }
            return $null
        }

        try {
            $foundFolder = Search-Folders -UserPrincipalName $UserPrincipalName -FolderName $FolderName
            if ($null -eq $foundFolder) {
                Write-Error "Folder '$FolderName' not found in user '$UserPrincipalName''s mailbox."
            } else {
                $foundFolder
            }
        } catch {
            Write-Error "Failed to retrieve folders for user '$UserPrincipalName': $_"
        }
    }
}

function Get-MailFolderMessages {
    [CmdletBinding(DefaultParameterSetName = 'Top')]
    param(
        [Parameter(
            Mandatory = $true,
            ValueFromPipeline = $true,
            HelpMessage = "The folder object returned from Find-MailFolderByName."
        )]
        [ValidateNotNull()]
        [PSCustomObject]$Folder,

        [Parameter(Mandatory = $false, HelpMessage = "The UPN of the mailbox owner. If not supplied, will use Folder.UserPrincipalName.")]
        [string]$UserPrincipalName,

        [Parameter(ParameterSetName = 'All', Mandatory = $true, HelpMessage = "Return all messages (paginated automatically).")]
        [switch]$All,

        [Parameter(ParameterSetName = 'Top', Mandatory = $false, HelpMessage = "Specify the number of messages to return (default: 10).")]
        [ValidateRange(1,1000)]
        [int]$Top = 10
    )
    begin {
        if (-not (Get-Module -ListAvailable -Name Microsoft.Graph.Users.Functions)) {
            throw "Microsoft.Graph.Mail module not found. Install it using Install-Module Microsoft.Graph.Mail"
        }
        Import-Module Microsoft.Graph.Users.Functions -ErrorAction Stop
    }
    process {
        try {
            if (-not (Get-EntraContext)) {
                Connect-Entra #-Scopes "Mail.Read"
            }
        } catch {
            throw "Failed to connect to Microsoft Graph: $_"
        }
        try {
            # Prefer explicit parameter, but use folder property if available
            $UPN = if ($UserPrincipalName) { $UserPrincipalName } elseif ($Folder.PSObject.Properties['UserPrincipalName']) { $Folder.UserPrincipalName } else { $null }
            if (-not $UPN) {
                throw "UserPrincipalName must be provided either as a parameter or on the Folder object."
            }

            if ($All) {
                Get-MgUserMailFolderMessageDelta -UserId $UPN -MailFolderId $Folder.Id -All
            } else {
                (Invoke-MgGraphRequest -Method Get -Uri "https://graph.microsoft.com/v1.0/users/$UPN/mailFolders/$($Folder.Id)/messages?`$top=$Top" -OutputType PSObject).value
                #Get-MgUserMailFolderMessageDelta -UserId $UPN -MailFolderId $Folder.Id -Top $Top
            }
        } catch {
            Write-Error "Failed retrieving messages from folder '$($Folder.DisplayName)' for user '$UPN': $_"
        }
    }
}