Managing distribution groups (DLs) within an organization is essential for keeping communications streamlined and secure and Active Directory and EntraID clean. Distribution groups that are no longer in use create clutter and unnecessary maintenance tasks. To address this, I developed a PowerShell script that checks for active and inactive distribution groups based on email activity within the last 10 days. The reason it is only 10 days, is that is how long Exchange keeps message trace logs, if you want to go back further than 10 days you need to perform a Start-HistoricalSearch . The history search only allows for up to 100 jobs at a time and is time consuming to run if your organization has a large number of distribution lists. I chose to run the script once every 10 days and track the usage with and unused Active Directory attribute that you can report on later in the future.
Script Overview: Distribution Group Cleanup
This PowerShell script connects to Exchange Online, retrieves email activity for all distribution groups, and classifies them as active or inactive based on recent usage. It then updates Active Directory attributes to track activity and emails a report with the details. If the email distribution group is used, it will then write the attribute to zero. One thing to note, if you have nested groups be careful when using this script. Nested groups will not show up in this report due to how Exchange expands distribution list. You need to make sure that the groups you are looking to remove are not part of a distribution group that is still in use. If you have security enabled distribution groups, this script will not be able to report on usage on those.
Key Features of the Script:
Step-by-Step Breakdown
- SMTP Email Setup: The script begins by defining the variables needed to send reports via email:
$From = "xxx@xxx.com"
$SMTPServer = "xxx.xxx.xxx"
$To = "xxx@xxx.com"
$AminAddress = "xxx@xxx.com"- Connect to Exchange Online: Using Connect-ExchangeOnline, the script connects to your organization’s Microsoft 365 environment securely using a certificate and AppID:
Connect-ExchangeOnline -CertificateThumbPrint "xxx" -AppID "xxx" -Organization "yourorg.onmicrosoft.com"- Retrieve Email Activity: The script collects message trace data from the last 10 days and stores it in an array for comparison against all distribution groups:
[array]$CurrentMessages = (Get-MessageTrace -Status Expanded -PageSize 5000 -Page $Page -StartDate $StartDate -EndDate $EndDate | Select-Object RecipientAddress, Received)- Classify Distribution Groups: Each distribution group is evaluated to see if it received any emails in the past 10 days. Based on that evaluation, the group is classified as either active or inactive:
If ($MessageTable -Match $DL.PrimarySMTPAddress) {
$ActiveStatus = "Active"
} Else {
$ActiveStatus = "Inactive"
}- Update Active Directory Attributes: The script updates custom attributes in Active Directory to track how long a group has been inactive. Active groups have their attribute reset to 0, while inactive groups have it incremented:
set-distributiongroup -identity $line.smtp -CustomAttribute10 0- Reporting: The script generates two CSV files: one for active groups and another for inactive groups. These are then attached to an email report, which is sent to the designated recipient:
Send-MailMessage -From "$From" -To "$To" -Subject "Distribution Group Cleanup Report" -Body $HtmlReport -BodyAsHtml -SmtpServer "$SMTPServer" -Attachments $CSVFile, $CSVFileActive- Disconnect and Cleanup: After processing the data, the script disconnects from Exchange Online and removes the snap-ins used:
Disconnect-ExchangeOnline -Confirm:$false
remove-PSSnapin Microsoft.Exchange.Management.```powershell.SnapInWhy Use This Script?
This PowerShell script automates the time-consuming task of tracking email activity for distribution groups, classifying them as active or inactive, and reporting the results to administrators. By updating AD attributes, it allows for easy tracking of inactive groups, ensuring that distribution groups are properly maintained and cleaned up when necessary.
Customization
The script’s default window for evaluating email activity is set to 10 days, but this can easily be adjusted:
$StartDate = $EndDate.AddDays(-10)This script can be scheduled to run regularly, ensuring that your environment is kept clean and that unused distribution groups are identified and managed proactively.
Final Thoughts
Automating the cleanup of distribution groups in Microsoft 365 not only reduces administrative overhead but also ensures that your organization is running efficiently. With this script, you can easily keep track of unused distribution groups and take action accordingly. You can run this script manually or schedule it to run on a weekly basis.
Download the script today and make managing distribution groups easier!
Stay organized, stay efficient!