Upgrade distribution lists to Office 365 Groups in Outlook

Contributors: Diane Faigel
Last updated: 6 September, 2017

It's easy to upgrade distribution lists to Office 365 Groups in Outlook! This is a great way to give your organization's distribution lists all the features and functionality of Office 365 groups. Why you should upgrade your distribution lists to groups in Outlook

You can upgrade DLs one at a time, or several at the same time.

Upgrade one or many distribution lists to Office 365 Groups in Outlook

  1. Sign in with your admin account at https://aka.ms/admincenter.

    Sign in with your Office 365 admin account at https://portal.office.de/adminportal/home#/homepage.

    Sign in to Office 365 operated by 21Vianet.

  2. Go to Admin centers > Exchange.

  3. In the Exchange Admin Center, go to Recipients  >  Groups.

    You'll see a notice indicating you have distribution lists (also called distribution groups) that are eligible to be upgraded to Office 365 groups.

    Click on Get started.

  4. Select one or more distribution lists (also called a distribution group) from the groups page.

    Select a distribution group from the groups page
  5. Choose the upgrade icon.

    Click or tap the Upgrade to Office 365 groups icon
  6. On the information dialog, choose Yes to confirm the upgrade. The process begins immediately. Depending on the size and number of DLs you're upgrading, the process can take minutes or hours. .

    If the distribution list can't be upgraded, a dialog appears saying so. See Which distribution lists can be upgraded.

  7. If you're upgrading multiple distribution lists, use the drop down to filter which distribution lists have been upgraded. If the list isn't complete, wait a while longer and then choose Refresh to see what's been successfully upgraded.

    There's no notice that tells you when the upgrade process has completed for all DLs you selected. You can figure this out by looking to see what's listed under Available for upgrade or Upgraded DLs.

  8. If you selected a DL for upgrade, but it's still appears on the page as Available to upgrade, then it failed to upgrade. See What to do if the upgrade doesn't work.

Note: If you're getting the groups digest emails you may notice at the bottom that it will sometimes offer to let you upgrade any eligible distribution lists that you're the owner of. See Have a group conversation in Outlook for more information about digest emails.

Upgrade a single distribution list to an Office 365 Group in Outlook on the web

Note: This new feature is gradually rolling out world wide. If you don't see the Upgrade option, you don't yet have it. Check back soon!

In Outlook on the web, distribution list owners will see a list of their eligible distribution lists under the Groups section of the navigation pane on the left. To upgrade a distribution list simply click on it, then click Upgrade in the dialog box that appears.

Click on the distribution list you wish to upgrade to a group Click your DL in the navigation pane then choose "Upgrade"

This option is only available to distribution list owners who have permissions to create Office 365 Groups.

Wondering which distribution lists are eligible? See Which distribution lists can be upgraded?

What to do if the upgrade doesn't work

Distribution lists that fail to upgrade remain unchanged.

If one or more eligible distribution lists fail to be upgraded, open a Support ticket. The issue will need to be escalated to the Groups Engineering team for them to figure out the problem.

It's possible that the distribution list didn't get upgraded because of a service outage, but pretty unlikely. If you want, wait a while and then try to upgrade the DL again.

How to use PowerShell to upgrade several distribution lists at the same time

If you're experienced at using PowerShell, you might want to go this route instead of using the UI. We have a nice packet of scripts that will help you upgrade distribution lists in bulk. These scripts will check if your distribution lists are eligible to be upgraded, and then help you with the upgrade.

Note: You can also upgrade a single distribution list to an Office 365 group using the New-UnifiedGroup PowerShell cmdlet.

  • Download the script files from the Microsoft download center.

  • Verify you're using PowerShell 3.0.

  • Run the $env:PSModulePath.Split(";")[0] command in PowerShell to output a directory path. Copy the module DlMigrationModule.psm1 and strings file DlMigration.strings.psd1 to the directory location.

List of upgrade scripts and what they do

  • Get-DlEligibilityList.ps1 - this script goes through all the distribution lists in your organization, outputs a detailed eligibility file ( DlEligibilityList.txt) and lists which distribution lists are eligible for updated. The file will contain the following info about the distribution lists: ExternalDirectoryObjectId, PrimarySmtpAddress, Alias, Name, Display Name, Eligibility, Reasons, Member Count, MemberSmtpList, OwnersDistinguishedName.

    To learn more, see Which distribution lists can be upgraded.

  • Convert-DistributionGroupToUnifiedGroup.ps1 - this script performs the conversion and migration of the distribution lists selected in the DlEligibilityList.txt file, and writes the result to the MigrationOutput.txt file.

    The MigrationOutput.txt file will also contain the following info about the distribution lists: DL-ExternalDirectoryObjectId, DL-PrimarySmtpAddress, UG-ExternalDirectoryObjectId, UG-PrimarySmtpAddress, MigrationStatus, Error Message

  • DlMigrationModule.psm1 - This module has the logic for eligibility and migration which are used by the Get-EligibilityList and Convert-DistributionGroupToUnifiedGroup scripts.

  • DlMigration.strings.psd1 - localized messages shown by the migration script, based on your browser language settings.

How to run the upgrade scripts

If you plan to span the upgrade over several days, make sure you download the latest scripts before you start the migration.

  1. Connect to Exchange PowerShell

  2. Run the Get-DlEligibilityList.ps1 script. The results will be saved to DlEligibilityList.txt file in the working directory.

    Get-DlEligibilityList.ps1 –WorkingDir “C:\Users\Administrator\Desktop\Migration” 
  3. You can make a copies of the DlEligibilityList.txt file, remove the rows you don't want to upgrade, and use this DlEligibilityList.txt file in the next step. Don't change the format of the .txt file

  4. Run the Convert-DistributionGroupToUnifiedGroup.ps1 script. The results will be saved to MigrationOutput.txt in the working directory.

    Convert-DistributionGroupToUnifiedGroup.ps1 -WorkingDir “C:\Users\Administrator\Desktop\Migration” –DlEligibilityListPath “C:\Users\Administrator\Desktop\Migration\DlEligibilityList.txt”
  5. Check the MigrationOutput.txt file to verify your migrations worked.

  6. Verify that your new Office 365 groups have been created in your organization by checking the Office 365 admin center.

    See your new Office 365 groups in the admin center preview

    The distribution lists Smtp Address and Alias will be renamed and the distribution list will be hidden from address lists.

Check your migration status

  • MigrationOutput.txt - this file tells you the status of your migrations. These are the statuses you'll see in the file:

    • Success – migration completed successfully.

    • Failure – migration failed and the error message column gives the details.

    • NotEligible – distribution list does not satisfy the eligibility criteria.

    • SuccessActionRequired – distribution list was upgraded with all the members and properties but there is some issue in reusing SMTP or deleting the distribution list. The error message will have the appropriate Info needed for taking the action.

    • FailureActionRequired - Migration failed. There is some action needed on the Admin as a cleanup of unused groups.

    • UnknownError – Look at error message column for more details.

FAQ about upgrading distribution lists to Office 365 Groups in Outlook

Which distribution lists can be upgraded?

You can only upgrade cloud-managed, simple, non-nested distribution lists. The table below lists distribution lists that CANNOT be upgraded.



On-premises managed distribution list.


Nested distribution lists. Distribution list either has child groups or is a member of another group.


Distribution lists with member RecipientTypeDetails other than UserMailbox, SharedMailbox, TeamMailbox, MailUser


Distribution list which has more than 100 owners


Distribution list which only has members but no owner


Distribution list which has alias containing special characters


If the distribution list is configured to be a forwarding address for Shared Mailbox


If the DL is part of Sender Restriction in another DL.


Security groups


Dynamic Distribution lists


Distribution lists which were converted to RoomLists


The Get-DlEligibilityList.ps1 script goes through all the distribution lists in your organization and outputs an eligibility file which lists which distribution lists are eligible to be upgrade. You can use the member and owner details to send out upgrade notifications or determine the time taken for ugprade.

Here are the definitions of eligibility in the script.

  • Eligible - The distribution list can be upgraded to Office 365 with all the functionality of an Office 365 group.

  • Information - The distribution list can be upgraded to an Office 365 group, but we want to provide some additional details regarding the functionality of the group.

  • Warning - The distribution list can be upgraded to an Office 365 group with most of the functionality. A few non critical things might not work. You can choose to upgrade distribution lists by using a parameter in the scripts.

  • NotEligible – These distribution lists can't be upgraded to an Office 365 group.

Who can run the upgrade scripts?

All admins who have permissions to run the New-UnifiedGroup cmdlet can run the script.

How long do the scripts run and are there any limits?

For a single connection, Get-DlEligibilityList.ps1 takes about 25 minutes to check the eligibility of about 300 distribution lists. The time it takes to run the Convert-DistributionGroupToUnifiedGroup.ps1 depends on the number of members in the distribution lists to be upgraded. It takes a about 1 minute for every 250 members. You can set -NoOfConnections parameter to 2 or 3 to make the script faster.

If the number of distribution lists in your organization is more than 5000, or if the eligibility script seems to be stuck, and there’s no output on the PowerShell console for hours, split the distribution lists covered by the Get-DlEligibilityList.ps1 script by using the -CustomFilterOnAlias parameter, and run the migration steps on each set separately. For example, if the -CustomFilterOnAlias @("a*","b*") is passed as input, then the eligibility script only looks at the distribution lists whose alias starts with a or b.

What does the status ‘Running’ mean in the MigrationOutput.txt file?

It means this distribution list was picked up for migration but we don't have the final status available. This happens when you hit Ctrl+C or try to stop the script in progress, or when the session is disconnected because of network or system issues.

In this case, if –DeleteDlAfterMigration wasn't set to true, you can check the status of the distribution list by doing a Get-DistributionGroup using the distribution lists ExternalDirectoryObjectId (present in MigrationOutput.txt). If the distribution list was upgraded, the SMTP of the distribution list will have the GUID of the Office 365 group. Get-UnifiedGroup <GUID> returns the group details. Check if the SMTP address on the group is as expected.

If the –DeleteDlAfterMigration parameter was set to true, you can check the status of the distribution list by a doing Get-DistributionGroup using the distribution lists ExternalDirectoryObjectId. If there are no results, it means the distribution list was upgraded successfully. If the distribution list still exists and the SMTP address isn't changed, then group creation failed. If distribution list exists with renamed SMTP containing the GUID, run Get-UnifiedGroup <GUID> to look at the group details. Also verify the SMTP address of the distribution list and the Office 365 group.

How can I delete a group created in Azure AD in case of FailureActionRequired?

Run Remove-MsolGroup cmdlet in Azure Active Directory by passing the Office group Id present in the error message.

Remove-MsolGroup –ObjectId GUID

Check out Azure Active Directory cmdlets.

Can I run the script in batches?

You’ll have an option to specify the batch size as an input. For example, if the batch size is specified as 100, then after processing every 100 * n [Number of connections] distribution lists, the processed and succeeded counts will be shown in the PowerShell console. For the Convert-DistributionGroupToUnifiedGroup.ps1 script, after every batch you’ll be prompted to confirm if you want to continue.

Batch size should be chosen based on the approximate estimated time to run each batch, so you can stop the script if you wish. If you hit Ctrl-C or close when running the Convert-DistributionGroupToUnifiedGroup.ps1 script, you won’t know the status of the current distribution list being upgraded. For example, if 10 distribution lists are being upgraded in a batch and you hit Ctrl + C while the 7th distribution list was being upgraded, status will be available for the first 6 distribution lists. The 7th distribution list status will be missing.

How do I list all the distribution lists in my organization that are already upgraded but not deleted?

$migratedDls = Get-DistributionGroup -Filter { Alias -Like 'MigratedDl-*' } | ForEach-Object { $guid = $_.Alias.Replace("MigratedDl-",""); $group = Get-UnifiedGroup $guid; if($group -ne $null) { Echo $_ } }

What should I do if the system is shutdown or I closed PowerShell accidentally?

If the system shut down while you were running the Get-DlEligibilityList.ps1, rerun the script using -ContinueFromPrevious switch.

If the system shutdown while you were running the Convert-DistributionGroupToUnifiedGroup.ps1 script, rerun the Convert-DistributionGroupToUnifiedGroup.ps1 script. You don't need to rerun the Get-DlEligibilityList.ps1 script. Take a look at the latest archive of the MigrationOutput.txt file and check the state of distribution lists with "Running" status.

What should I do in case the SMTP address isn't reused or the SMTP address isn't unique?

Identify the recipient which is using the same SMTP address using the Get-Recipient <SMTP> or Get-UnifiedGroup cmdlets. Make a call on which object should have this SMTP either distribution list / Group / Recipient. Update the addresses on these objects using –EmailAddresses parameter on Set-UnifiedGroup or Set-DistributionGroup.

Can I pipe the output from the DlEligibilityList.txt file to the Convert-DistributionGroupToUnifiedGroup.ps1 script?

You can pipe the output from DlEligibilityList.txt file to the Convert-DistributionGroupToUnifiedGroup.ps1 script. In this case, all eligible distribution lists and their data will be upgraded. Non-eligible distribution lists will not be upgraded. If there's non-eligible distribution lists in the DlEligibilityList.txt file, it takes longer to run the script since it'll check eligibility again.

Why is the contact card still showing a distribution list? What should I do to prevent a upgraded distribution list from showing up in my auto suggest list?

  • For Outlook

    • When someone tries to send an email in Outlook by typing the Office 365 group name after migration, the recipient will be resolved as the distribution list instead of the Office 365 group. The contact card of the recipient will be the distribution lists contact card. This is because of the recipient cache or nick name cache in Outlook. The email will be sent successfully to the Office 365 group, but might cause confusion to the sender.

      You can perform the steps in this topic, Information about the Outlook AutoComplete list to reset the cache, which will fix this issue.

  • For Outlook on the web

Do new group members get a welcome email in their inbox?

No. The setting to enable welcome messages is set to false by default. This setting affects both existing and new group members who may join after the migration is complete. If the group owner later allows guest users, guest users won't receive a welcome email in their inbox. Guest members can continue working with the group.

What happens to the DL if the upgrade from EAC fails?

The upgrade will happen only when the call is submitted to the server. If the upgrade fails, your DLs will be intact. They will work like they used to.

Commonly used parameters

  • ConvertClosedDlToPrivateGroup - By default a closed distribution list will be converted to a private group. If you don't want to convert the closed distribution list to a private group, set the ConvertClosedDlToPrivateGroup parameter to $false.

  • DeleteDlAfterMigration - If this parameter is set to $true while running the Convert-DistributionGroupToUnifiedGroup.ps1, the distribution list will be deleted if the migration is successful.

  • NoOfConnections - Number of parallel connections that can be used for migration. Range 1-3. Default is 1. If we choose to use 3 then you will not be able to open any new Exchange powershell sessions till the scripts complete.

  • Credential - Admin Login credentials for opening new sessions in case NoOfConnections is specified.

  • WorkingDir - The path where logs and output files of the script will be stored. Default: Current working directory.

  • ContinueFromPrevious - When this parameter is set to true, the script tries to look at the output files of the previous run in the working directory and continue from the point where it was stopped. For this to work, the WorkingDir passed should be same as the run from which the admin wants to continue. Exchange doesn't store any status about the previous run, it's stored in the files in the WorkingDir. This parameter is only available in the Get-DlEligibilityList.ps1 script.

  • Every time the Convert-DistributionGroupToUnifiedGroup.ps1 script is run, any MigrationOutput.txt files from previous migration runs will be archived as MigrationOutput_yyyyMMddHHmmss.txt and a new output file will be created. If you want to use the same input file over multiple runs, remove those rows which were completed and then rerun. The script doesn't remember the previous output so it will attempt to upgrade the processed distribution lists again and may lead to an extra time overhead. The output will say distribution list is invalid if the distribution list was already upgraded, otherwise, it’ll retry.

The short icon for LinkedIn Learning. New to Office 365?
Discover free video courses for Office 365 admins and IT pros, brought to you by LinkedIn Learning.

Expand your skills
Explore training
Get new features first
Join Office Insiders

Was this information helpful?

Thank you for your feedback!

Thank you for your feedback! It sounds like it might be helpful to connect you to one of our Office support agents.