Public/Sync/func_Sync-GALMailbox.ps1

function Sync-GALMailbox {
    [CmdletBinding(SupportsShouldProcess)]
    param (
        [parameter(Mandatory)][string]$Mailbox,
        [parameter(Mandatory)][string]$ContactFolderName,
        [parameter(Mandatory)][AllowEmptyCollection()][object[]]$DirectoryUser,
        # report unavailable mailboxes as Failed instead of Skipped, used for explicitly requested mailboxes
        [switch]$FailWhenUnavailable
    )
    # mailboxes without Exchange Online (no licence, deleted, not a user mailbox) can not be synced
    $skipCodes = "MailboxNotEnabledForRESTAPI", "MailboxNotSupportedForRESTAPI", "ErrorNonExistentMailbox", "ErrorInvalidUser", "ResourceNotFound"
    $result = [ordered]@{
        Mailbox   = $Mailbox
        Status    = "Succeeded"
        Created   = 0
        Updated   = 0
        Removed   = 0
        Unchanged = 0
        Failed    = 0
        Message   = $null
    }

    try {
        $folders = @(Get-GALContactFolder -Mailbox $Mailbox -Name $ContactFolderName)
        $managed = @($folders | Where-Object { $_.isManaged })
        if ($folders -and -not $managed) {
            throw "$Mailbox already has a contact folder named $ContactFolderName that was not created by GAL-Sync"
        }
        $folder = $managed | Select-Object -First 1
        $contacts = @(if ($folder) { Get-GALFolderContact -Mailbox $Mailbox -FolderId $folder.id })
        $plan = Get-SyncPlan -DirectoryUser $DirectoryUser -FolderContact $contacts
        $result.Unchanged = $plan.Unchanged
        $action = "Create $($plan.Create.Count), update $($plan.Update.Count) and remove $($plan.Remove.Count) contact(s) in $ContactFolderName"

        if (-not ($plan.Create -or $plan.Update -or $plan.Remove -or -not $folder -or $managed.Count -gt 1)) {
            Write-VerboseEvent "$Mailbox is up to date"
        }
        elseif (-not $PSCmdlet.ShouldProcess($Mailbox, $action)) {
            $result.Status = "WhatIf"
            $result.Created = $plan.Create.Count
            $result.Updated = $plan.Update.Count
            $result.Removed = $plan.Remove.Count
        }
        else {
            if (-not $folder) {
                Write-VerboseEvent "Creating contact folder $ContactFolderName for $Mailbox"
                $folder = New-GraphRequest -Method Post -Endpoint (Get-FolderEndpoint -Mailbox $Mailbox) -Body @{
                    displayName                   = $ContactFolderName
                    singleValueExtendedProperties = @($script:folderMarker)
                }
            }
            # two runs at the same time can both create the folder
            foreach ($duplicate in $managed | Select-Object -Skip 1) {
                Write-Warning "Removing duplicate contact folder $ContactFolderName from $Mailbox"
                New-GraphRequest -Method Delete -Endpoint (Get-FolderEndpoint -Mailbox $Mailbox -FolderId $duplicate.id) | Out-Null
            }

            $contactsEndpoint = "$(Get-FolderEndpoint -Mailbox $Mailbox -FolderId $folder.id)/contacts"
            $phases = [ordered]@{
                Removed = foreach ($contact in $plan.Remove) {
                    @{
                        action = "remove"
                        name   = $contact.displayName
                        method = "DELETE"
                        url    = "$contactsEndpoint/$([System.Uri]::EscapeDataString($contact.id))"
                    }
                }
                Updated = foreach ($change in $plan.Update) {
                    Write-VerboseEvent "Updating $($change.Body.displayName) in $($Mailbox): $($change.Changes -join ", ")"
                    @{
                        action = "update"
                        name   = $change.Body.displayName
                        method = "PATCH"
                        url    = "$contactsEndpoint/$([System.Uri]::EscapeDataString($change.Contact.id))"
                        body   = $change.Body
                    }
                }
                Created = foreach ($body in $plan.Create) {
                    @{
                        action = "create"
                        name   = $body.displayName
                        method = "POST"
                        url    = $contactsEndpoint
                        body   = $body
                    }
                }
            }
            foreach ($counter in $phases.Keys) {
                $requests = @($phases[$counter])
                $responses = @(New-GraphBatchRequest -Requests $requests)
                for ($index = 0; $index -lt $requests.Count; $index++) {
                    $status = $responses[$index].status
                    if ($status -ge 200 -and $status -lt 300) {
                        $result[$counter]++
                        continue
                    }
                    $result.Failed++
                    Write-Warning "Failed to $($requests[$index].action) contact $($requests[$index].name) in $($Mailbox): $(Format-ErrorCode -StatusCode $status -ErrorBody $responses[$index].body)"
                }
            }
            if ($result.Failed) {
                $result.Status = "CompletedWithErrors"
                $result.Message = "$($result.Failed) contact change(s) failed"
            }
        }
    }
    catch {
        $result.Message = $_.Exception.Message
        $errorCode = $_.Exception.Data["GraphErrorCode"]
        if ($errorCode -eq "ErrorAccessDenied") {
            $result.Message += " (check that the app has Contacts.ReadWrite, granted in Entra or through Exchange RBAC for Applications, and that the mailbox is in scope)"
        }
        if ($errorCode -in $skipCodes -and -not $FailWhenUnavailable) {
            $result.Status = "Skipped"
            Write-VerboseEvent "Skipped $($Mailbox): $($result.Message)"
        }
        else {
            $result.Status = "Failed"
            Write-Warning "Failed to sync mailbox $($Mailbox): $($result.Message)"
        }
    }
    return [pscustomobject]$result
}