Automating Office 365 Distribution Group Management with PowerShell

# Minimum required version of the ExchangeOnlineManagement module
$minVersion = "2.0.3"

# Check if the ExchangeOnlineManagement module is installed
if (!(Get-Module -ListAvailable -Name ExchangeOnlineManagement)) {
    # If not installed, install the module
    Install-Module -Name ExchangeOnlineManagement -Force -AllowClobber
} else {
    # If installed, check its version
    $installedVersion = (Get-Module -ListAvailable -Name ExchangeOnlineManagement).Version

    # If the installed version is less than the minimum required version, update it
    if ($installedVersion -lt $minVersion) {
        Update-Module -Name ExchangeOnlineManagement -Force
    }
}

# Function to convert email to a valid alias
function ConvertTo-ValidAlias($email) {
    $cleanedEmail = $email -replace '@', '_at_' -replace '.', '_dot_'
    if ($cleanedEmail.Length -gt 64) {
        # Take the first 10 characters and add a hash for uniqueness
        $cleanedEmail = $cleanedEmail.Substring(0, 10) + "_" + $email.GetHashCode()
    }
    return $cleanedEmail
}

# Import module
Import-Module ExchangeOnlineManagement

# Parameters file path
$parametersFilePath = "$PSScriptRoot\parameters.json"

# Prompt for parameters or use saved ones
if (Test-Path $parametersFilePath) {
    $useSavedParameters = Read-Host "Would you like to use the previously entered parameters? (yes/no)"
    if ($useSavedParameters.ToLower() -eq 'yes') {
        $parameters = Get-Content $parametersFilePath | ConvertFrom-Json
    }
}

if ($null -eq $parameters) {
    # Prompt for user's email address
    $userEmail = Read-Host "Please enter your email address"

    # Prompt for the path of the CSV file
    $csvPath = Read-Host "Please enter the full path to your CSV file"

    # Prompt for the name of the distribution group
    $groupName = Read-Host "Please enter the email address of the distribution group"

    # Save parameters for next time
    $parameters = @{
        userEmail = $userEmail
        csvPath = $csvPath
        groupName = $groupName
    }

    $parameters | ConvertTo-Json | Out-File $parametersFilePath
}

# Connect to Exchange Online with MFA, it will prompt for credentials
Write-Host "Connecting to Exchange Online..."
try {
    Connect-ExchangeOnline -UserPrincipalName $parameters.userEmail -ShowProgress $true -ErrorAction Stop
    Write-Host -ForegroundColor Green "Connected to Exchange Online successfully."
}
catch {
    Write-Host -ForegroundColor Red "Failed to connect to Exchange Online. Error: $($_.Exception.Message)"
    exit
}

# Check if the group exists, if not, create it
$groupExists = Get-DistributionGroup -Identity $parameters.groupName -ErrorAction SilentlyContinue

if (!$groupExists) {
    Write-Host "Creating distribution group: $($parameters.groupName)..."
    try {
        New-DistributionGroup -Name $parameters.groupName -Type Distribution -ErrorAction Stop
        Write-Host -ForegroundColor Green "Distribution group created successfully."
    }
    catch {
        Write-Host -ForegroundColor Red "Failed to create distribution group. Error: $($_.Exception.Message)"
        Disconnect-ExchangeOnline -Confirm:$false
        exit
    }
}

# Read the CSV file
Write-Host "Reading email addresses from CSV file..."
try {
    $emailAddresses = Import-Csv -Path $parameters.csvPath
    Write-Host -ForegroundColor Green "CSV file read successfully."
}
catch {
    Write-Host -ForegroundColor Red "Failed to read CSV file. Error: $($_.Exception.Message)"
    Disconnect-ExchangeOnline -Confirm:$false
    exit
}

# Loop through the list of email addresses
foreach ($email in $emailAddresses) {
    # Output the email address it's trying to process
    Write-Host "Processing email: $($email.Email)"

    # Check if the email is a pre-existing internal user
    $internalUser = Get-User -Identity $email.Email -ErrorAction SilentlyContinue

    if ($internalUser) {
        # If the email is an internal user, add them to the group
        Write-Host "Adding internal user $($email.Email) to the group..." -NoNewline
        try {
            Add-DistributionGroupMember -Identity $parameters.groupName -Member $internalUser.UserPrincipalName -ErrorAction Stop
            Write-Host -ForegroundColor Green "Success."
        }
        catch {
            Write-Host -ForegroundColor Red "Failed. Error: $($_.Exception.Message)"
        }
        continue
    }

    # Check if the contact already exists
    $alias = ConvertTo-ValidAlias $email.Email
    $contact = Get-MailContact -Identity $alias -ErrorAction SilentlyContinue

    if (!$contact) {
        # Create a contact
        Write-Host "Creating contact for $($email.Email)..." -NoNewline
        try {
            $contact = New-MailContact -ExternalEmailAddress $email.Email -Name $email.Email -Alias $alias -ErrorAction Stop
            Write-Host -ForegroundColor Green "Success."
        }
        catch {
            Write-Host -ForegroundColor Red "Failed. Error: $($_.Exception.Message)"
            continue
        }
    }

    # Add the contact to the distribution group
    Write-Host "Adding contact $($email.Email) to the group..." -NoNewline
    try {
        Add-DistributionGroupMember -Identity $parameters.groupName -Member $contact.PrimarySmtpAddress -ErrorAction Stop
        Write-Host -ForegroundColor Green "Success."
    }
    catch {
        Write-Host -ForegroundColor Red "Failed. Error: $($_.Exception.Message)"
    }
}

# Disconnect from Exchange Online
Write-Host "Disconnecting from Exchange Online..."
Disconnect-ExchangeOnline -Confirm:$false
Write-Host -ForegroundColor Green "Disconnected from Exchange Online."

# Cleanup
Remove-Variable -Name parametersFilePath, useSavedParameters, minVersion, userEmail, csvPath, groupName, groupExists, emailAddresses, email, internalUser, alias, contact -ErrorAction SilentlyContinue