PS365

0.5.1

Public/Exchange/Mailbox/Get/Get-ExMailboxProtocol.ps1

<#
    .SYNOPSIS
    Retrieves mailbox protocol settings for Exchange Online mailboxes.
 
    .DESCRIPTION
    This function retrieves the protocol settings (MAPI, OWA, IMAP, POP, EWS, ActiveSync)
    for Exchange Online mailboxes. It can filter mailboxes by identity or by domain.
    Additionally, it provides information about SMTP Client Authentication settings
    at both the mailbox and tenant levels.
 
    .PARAMETER Identity
    The identity of the mailbox to retrieve protocol settings for.
    If not specified, the function retrieves settings for all mailboxes.
 
    .PARAMETER ByDomain
    The domain to filter mailboxes by. Only mailboxes with a primary SMTP address in this
    domain will be processed.
 
    .PARAMETER ExportToExcel
    If specified, exports the results to an Excel file in the user's profile directory.
 
    .EXAMPLE
    Get-ExMailboxProtocol
 
    Retrieves mailbox protocol settings for all Exchange Online mailboxes.
 
    .EXAMPLE
    Get-ExMailboxProtocol -Identity "user@example.com"
 
    Retrieves mailbox protocol settings for the specified mailbox.
 
    .EXAMPLE
    Get-ExMailboxProtocol -ByDomain "example.com"
 
    Retrieves mailbox protocol settings for all mailboxes in the specified domain.
 
    .EXAMPLE
    Get-ExMailboxProtocol -ExportToExcel
 
    Exports mailbox protocol settings for all Exchange Online mailboxes to an Excel file in the user's profile directory.
 
    .LINK
    https://ps365.clidsys.com/docs/commands/Get-ExMailboxProtocol
#>

function Get-ExMailboxProtocol {
    param (
        [Parameter(Mandatory = $false, position = 0, ValueFromPipeline = $true, ValueFromPipelineByPropertyName = $true)]
        [ValidateNotNullOrEmpty()]
        [string]$Identity,

        [Parameter(Mandatory = $false)]
        [string]$ByDomain,

        [Parameter(Mandatory = $false)]
        [switch]$ExportToExcel,

        [Parameter(Mandatory = $false, HelpMessage = 'Optional output directory for the Excel export (defaults to the user profile).')]
        [string]$ExportPath
    )

    begin {
        $exoCasMailboxesArray = [System.Collections.Generic.List[PSCustomObject]]::new()
    }
    process {
        $tenantSmtpClientAuthenticationDisabled = (Get-TransportConfig).SmtpClientAuthenticationDisabled
        if ($tenantSmtpClientAuthenticationDisabled) {
            Write-Host 'SMTP Client Authentication is disabled' -ForegroundColor Green
            $tenantSmtpClientAuthenticationEnabled = $false
        }
        else {
            Write-Host 'SMTP Client Authentication is enabled' -ForegroundColor Yellow
            $tenantSmtpClientAuthenticationEnabled = $true
        }
        if ($ByDomain) {
            $casMailboxes = Get-EXOCasMailbox -ResultSize Unlimited -Filter "EmailAddresses -like '*@$ByDomain'" -PropertySets All | Where-Object { $_.PrimarySmtpAddress -like "*@$ByDomain" }
        }
        elseif ($Identity) {
            $casMailboxes = [System.Collections.Generic.List[PSCustomObject]]::new()
            try {
                $mbx = Get-EXOCasMailbox -Identity $Identity -PropertySets All
                $casMailboxes.Add($mbx)
            }
            catch {
                Write-Warning "Mailbox not found: $Identity"
            }
        }
        else {
            $casMailboxes = Get-EXOCasMailbox -ResultSize Unlimited -PropertySets All
        }
        foreach ($casMailbox in $casMailboxes) {

            $object = [PSCustomObject][ordered]@{
                PrimarySmtpAddress                    = $casMailbox.PrimarySmtpAddress
                DisplayName                           = $casMailbox.DisplayName
                ExchangeObjectId                      = $casMailbox.ExchangeObjectId
                MAPIEnabled                           = $casMailbox.MAPIEnabled
                OWAEnabled                            = $casMailbox.OWAEnabled
                UniversalOutlookEnabled               = $casMailbox.UniversalOutlookEnabled
                OutlookMobileEnabled                  = $casMailbox.OutlookMobileEnabled
                IMAPEnabled                           = $casMailbox.ImapEnabled
                POPEnabled                            = $casMailbox.PopEnabled
                EwsEnabled                            = $casMailbox.EwsEnabled
                ActiveSyncEnabled                     = $casMailbox.ActiveSyncEnabled
                # CMDlet returns SMTPClientAuthenticationDisabled but we want SMTPClientAuthenticationEnabled
                ECPEnabled                            = $casMailbox.ECPEnabled
                # we invert the value to provide SMTPClientAuthenticationEnabled because by default the cmdlet returns SMTPClientAuthentication*Disabled*
                SMTPClientAuthenticationEnabled       = if ($null -ne $casMailbox.SMTPClientAuthenticationDisabled) { -not $casMailbox.SMTPClientAuthenticationDisabled }else { '-' }
                TenantSmtpClientAuthenticationEnabled = $tenantSmtpClientAuthenticationEnabled
                MailboxWhenCreated                    = $casMailbox.WhenCreated
                MailboxWhenModified                   = $casMailbox.WhenChanged
            }

            $exoCasMailboxesArray.Add($object)
        }
    }
    end {
        if ($ExportToExcel.IsPresent) {
            $now = Get-Date -Format 'yyyy-MM-dd_HHmmss'
            $excelFilePath = "$(if ($ExportPath) { $ExportPath } else { $env:userprofile })\$now-ExMailboxProtocol.xlsx"
            Write-Host -ForegroundColor Cyan "Exporting mailbox protocols to Excel file: $excelFilePath"
            $exoCasMailboxesArray | Export-Excel -Path $excelFilePath -AutoSize -AutoFilter -WorksheetName 'ExchangeMailboxProtocols' -TableStyle Light9
            Write-Host -ForegroundColor Green 'Export completed successfully!'
        }
        else {
            return $exoCasMailboxesArray
        }
    }
}