Transforming Exchange Distribution Groups to Office 365 Groups

Posted on October 4, 2016 by Tony Redmond in Exchange Server, Office, Office 365, PowerShell with

Exchange GOM Office 365 Group

Microsoft says that it doesn’t recommend traditional email distribution groups (within Office 365) anymore. Although the company admits that Office 365 Groups can’t handle all the scenarios that distribution groups deal with today, pressure is building to move to Office 365 Groups whenever possible. Among the tools that exist to help make the change is a one-click option in the Exchange Online Administration Center (EAC). However, the option only works for distribution groups that consist of Exchange Online mailboxes. If a group contains any other mail-enabled object such as a public folder or external contact, the EAC option doesn’t work. That’s a problem because many distribution groups contain other types of email-enabled objects, such as other distribution groups, public folders, and mail contacts — or even Office 365 Groups.

When the time came to upgrade a particularly important distribution group, there was nothing to do but perform a manual conversion. And that’s when some problems arose, mostly caused by synchronization delays between Exchange Online and Azure Active Directory.



Using Modern Collaboration

Email is good at transmitting attachments, but it fails at maintaining an archive of those documents or indeed a record of the discussions that occur inside distribution groups. Since the dawn of Exchange 4.0 in 1996, the problem of needing an archive for discussions inside distribution groups has often been dealt with by adding a mail-enabled public folder to the membership of groups. But public folders are old-time technology now and something modern should be used instead, especially when collaborating in the cloud.

Some of the Exchange MVPs (hereafter known as the GOMs, or “grumpy old men”) use a private distribution group to communicate news, views, and complaints among the team. The distribution group is hosted in my Office 365 tenant and the MVPs are defined as mail contacts to allow them to participate in the distribution group.

We decided to exploit the new guest user access feature for Office 365 Groups and replace the old distribution group with a new Office 365 Group. In addition to email conversations that function very much like distribution groups, using an Office 365 Group allows members to share information in a SharePoint document library and OneNote notebook. There’s also the prospect of being able to tie in Microsoft Planner in the future, if the GOMs ever felt the need to assign tasks to each other.

Converting to an Office 365 Group

The strategy looked good on paper. Implementing it was another matter. The key step is to transform the set of existing mail contacts that form the membership of the distribution group into guest users and add them as members for the new Office 365 Group. There’s no automatic method to do so and as there were only 70-odd members to process, I didn’t feel like figuring out all the complexities that were involved in scripting the task with PowerShell. I figured that I could move the mail contacts over using the GUI as quickly as I would write and test the script, including the need to debug the inevitable errors introduced by my inability to code. The script remains a project for another day.

No magic is needed to transform mail contacts into guest users. The process is as follows:

  1. Note the SMTP email address of the mail contact.
  2. Use EAC or PowerShell to delete the mail contact.
  3. Add the email address of the deleted mail contact as a new guest user for the Office 365 Group. I used OWA for this purpose (as shown in Figure 1).
  4. Save and iterate until the full set of mail contacts are processed.
  5. Note the primary SMTP address of the old distribution group and then assign a new primary SMTP email address to the old distribution group.
  6. Remove the previous primary address from the distribution group and assign it as the primary address of the new Office 365 Group. Switching the addresses makes sure that replies to the old distribution group sent from outside the tenant will be redirected to the Office 365 Group.
Office 365 Group Guest user

Figure 1: Adding an external user as a guest member of an Office 365 Group (image credit: Tony Redmond)

The notion that the plan could be executed quickly was derailed by a couple of small glitches that made the process a little frustrating at times.

The Need for Synchronization

Azure Active Directory (AAD) is the master directory for Office 365. Different workloads have their own directories to hold information about objects that are specific to the workload. Thus, when you remove a mail contact, the delete operation has to be synchronized from EXODS, the directory used by Exchange Online, to AAD.


Synchronization between directories can take a little time to happen. Until the mail contact is purged from AAD, you won’t be able to use the SMTP address for the mail contact to create a new guest user for the Office 365 Group. The error message (shown in Figure 2) is a little misleading, as you’re not trying to add a contact created by your admin. Exchange Online doesn’t allow multiple objects to exist that use the same email address (of any type). In this case, you need to wait for synchronization to settle down and “free” the SMTP address for reuse.

Office 365 Groups Error 1

Figure 2: Whoops! The mail contact still exists in AAD (image credit: Tony Redmond)

Waiting for a minute or so should be sufficient to convince AAD that the SMTP address is available to be assigned to a new guest user account. Sometimes it took longer — it all depends on the current load that exists within Office 365.

As I had 70 new guest users to add to the group, I processed the guest users in batches while watching TV (to fill the gaps when synchronization occurred). After a set of guest users were added, I’d attempt to update the group and sometimes encounter the issue shown in Figure 3.

Office 365 Groups error 2

Figure 3: Some new guest members can be added to the Office 365 Group. Some can’t. Why? (image credit: Tony Redmond)

Once again, I concluded that a need for synchronization to finish is the reason why this problem happens. Two steps are needed to add a guest user to a group. First, the guest user account is created in AAD. Second, the linked list of group members has to be updated with the new guest user accounts. However, those new guest user accounts have to be synchronized from AAD to EXODS before they can be added to the membership list. Once again, waiting for a moment or so resolved the problem.

The Coding Approach

Given the need to wait for synchronization to happen, I was happy with my decision not to attempt to script the transformation. The code required is more complex than appears on the surface. It’s not just a matter of assembling a few cmdlets as follows:

  • Get-DistributionGroupMember to retrieve the membership of the old distribution list
  • Get-MailContact to retrieve the SMTP address of each DL member
  • Remove-MailContact to remove the old mail contact
  • New-MsolUser to add the new guest user using the SMTP address of the DL member
  • Iterate through the set of members
  • Switch the email addresses with Set-DistributionGroup and Set-UnifiedGroup. For instance, this command assigns the old address for the DL to the new Office 365 Group.

To accommodate synchronization, some waits must be incorporated in the code to ensure that objects are available before they are processed. Some error checking is needed, too. In short, writing and testing the PowerShell code required more effort than I cared to expend to get the group up and running. If anyone else wants to take on the challenge, they are more than welcome!

Keeping Mail Flowing

While I was busy moving objects around, I wanted to allow the Office 365 Group to receive email from external users. Because they are part of the group membership, guest users can send messages to the group like any other member, so nothing needs to be done to allow guest users to contribute to conversations via email. However, I wanted to keep conversations flowing while some people were members of the old distribution group and some add been moved across to the Office 365 Group. For this reason, I opened the Office 365 Group up so that any external user could contribute to conversations via email. Here’s the command I used:

Once all the group members are added, you can reverse course and set RequireSenderAuthenticationEnabled to $True to secure the group.

The Final Step

After all the members were moved across to the Office 365 Group, I added it as a member of the old distribution list to ensure that any reply sent to the old list would reach the new group. You can’t do this through any GUI, so PowerShell has to be used:

A Happy Group Is a Good Group

The outcome is that the move succeeded and we have a perfectly-functioning Office 365 Group. Email conversations continued to flow without missing a heartbeat (or more importantly, a message). The new group is ready to share documents once the GOMs decide what they’d like to share.


We know that some limitations exist. For instance, guest users can’t access the group with the Outlook Groups mobile app, yet. Nor can they use the OneDrive for Business sync client to synchronize the group document library to their PC. However, these are the finer points that Microsoft will get to in time. Until then, the grumpies are happy with their new home.

Follow Tony on Twitter @12Knocksinna.

Want to know more about how to manage Office 365? Find what you need to know in “Office 365 for IT Pros,” the most comprehensive eBook covering all aspects of Office 365. Available in PDF and EPUB formats (suitable for iBooks) or for Amazon Kindle.

Tagged with , , , , , , , , , ,

Register for this upcoming webinar on
Webinar: Accelerate Smart Factory ROI with Deloitte and HPE’s Digital IoT

Join HPE and Deloitte for a discussion on how to take advantage of IT and OT convergence to deliver the Factory of the Future

Tuesday, October 24, 2017
at 2 p.m. EST

Register for this upcoming webinar on
Webinar: Accelerate Smart Factory ROI with Deloitte and HPE’s Digital IoT

Join HPE and Deloitte for a discussion on how to take advantage of IT and OT convergence to deliver the Factory of the Future

Tuesday, October 24, 2017
at 2 p.m. EST