How to manage email addresses for Microsoft 365 Groups

Recently, I’ve run into several discussions around how to use the Graph API to change the email address of an already provisioned Microsoft 365 Group (or Team). In all of them, a claim was made that this is possible by changing the mailNickname (“alias”) property of the group, after which supposedly some process would kick in and update the primary SMTP address of the group. Spoiler alert, it doesn’t, and you cannot use the Graph API for such operations.

Since I had to run few tests to confirm this behavior, you will now suffer through another one of my articles, detailing the issue and the troubleshooting steps. Don’t worry, we will also provide a solution. If that’s what you are interested in, feel free to skip the first section completely.

Graph API cannot be used for this task!

First, let’s set the stage. We have some Microsoft 365 Groups created within our tenant, and for some reason the wrong email address was provisioned. This might be due to negligence/simple mistake, or because the group’s purpose has changed later on, or even something more complex as tenant divestiture. Regardless of the reason, we must change the email address of the Group to a more suitable value. Here is the set of relevant properties exposed by the Graph API:

• proxyAddresses – contains the set of addresses configured on a given group object. Read-only! Although the documentation mentions that only email addresses (i.e. the ones prefixed with “smtp”) are returned, you can expect to see some other types, such as the SPO ones.
• mail – in Graph, this will match the primary SMTP address of the Group object. The property is also marked as read-only!
• mailNickname – gives the mail “alias” for the group object. While usually its value matches the “alias” portion of the primary SMTP address (the part before the ‘@’ sign), this is not always the case.

Note that the above list only represents the properties relevant for Group objects. For user objects, you might also want to consider the otherEmails and imAddresses ones.

As a specific example, let’s take the Microsoft 365 Group shown on the screenshot below. A simple scenario, where the Group has Primary SMTP address associated with the tenant’s default domain, and a secondary address associated with the “service” domain. We use the Get-MgGroup cmdlet to show the property values as reported by the Graph API and the Get-UnifiedGroup cmdlet to compare them with the Exchange Online ones.  The address prefixed with “SPO:” is not relevant to our discussion and is shown only for the sake of completeness.

 

You might have already noted the root cause of our issue in the list above – both the proxyAddresses and mail properties are marked as read-only! In fact, let’s not trust the documentation on this one and verify this ourselves. The first example below is attempt to PATCH the value of the proxyAddresses attribute, which in theory should replace the current set of aliases with the provided one.

PATCH https://graph.microsoft.com/beta/groups/9001c37e-989a-4e54-80ca-c770536d610e
{
"proxyAddresses": [
"SMTP:SPO1@michev.info"
]
}

The second example tries to update the mail attribute:

PATCH https://graph.microsoft.com/beta/groups/9001c37e-989a-4e54-80ca-c770536d610e
{
    "mail": "SPO1@michev.info"
}

Both fail, as expected. Interestingly enough, if you try a PATCH operation and provide the current list of proxyAddresses, the request will succeed with 204 No Content response. Microsoft never fails to disappoint when it comes to consistency, especially in their error handling… Both error messages above are worded quite differently, but simply mean that the corresponding property cannot be managed with the Graph API methods.

The only property you can change via the Graph API methods is the mailNickname one. According to the posts I referred to above, by PATCH-ing the value of the mailNickname property, we can effectively force a change of the Primary SMTP address for the group. Or more precisely, the “alias” part of the Primary SMTP address – it will have no effect on the domain portion. So let’s try that, shall we:

PATCH https://graph.microsoft.com/beta/groups/9001c37e-989a-4e54-80ca-c770536d610e
{
"mailNickname": "testing123"
}

The operation succeeded, and at this point we can verify that the mailNickname attribute has a new value. However, nothing else has changed. Even after waiting for extended period, thus giving time for any background tasks to kick in, no change in either the mail or proxyAddresses attribute followed. Just to be on the safe side, I repeated the same process in few other tenants, with or without email address policies configured (more on this later), with existing and newly created groups. The results are the same – changing the mailNickname attribute’s value DO NOT result in changing the Groups’ email address!

As additional confirmation, I turned to the audit logs in order to fetch any events corresponding to the groups in question. In all tenants, the only entry I was able to find was the Update group. operation, showing the change of the MailNickname property. Nothing else, even though the entire timespan from said event forward was covered. At this point, my conclusion is that changing the mailNickname property has no effect whatsoever on the set of email addresses configured for the Microsoft 365 Group object. And, as none of the other properties are editable via the Graph API, the overall conclusion is that for the task at hand (changing the email address of an Microsoft 365 Group), no support is offered in the Graph API.

Exchange PowerShell does the job

So what does work then? As with any other email-related property, the answer is Exchange Online PowerShell and specifically, the Set-UnifiedGroup cmdlet. If you want a more technical explanation, the reason behind this is that ExODS is the source of authority for any Exchange-related attribute. Any changes made to attributes such as the proxyAddresses one must be executed against ExODS. A dual-write mechanisms is then responsible for replicating the changes to Azure AD, and only after a successful confirmation is received, the actual change will be committed to both directories. In other words, when making a change via Exchange Online PowerShell, you should expect to see at least two audit log events: one for the ExO cmdlet itself and one for the corresponding dual-write operation (which are all attributes to the same service principal, as we’ve complained on multiple occasions).

With that in mind, let’s now see what the corresponding properties look like on Exchange Online’s side of things. We have already shown their values in our example scenario on the first screenshot above.

• EmailAddresses – contains the set of addresses configured on a given group object. Compared to what the Graph is displaying in the corresponding proxyAddresses property, you might find other (non-email) addresses listed here.
• PrimarySmtpAddress – gives the primary SMTP address. Should match the mail property as reported via the Graph API.
• Alias – gives the mail “alias” for the group object. Matches Graph API’s mailNickname.

As in the Graph API case, we’re only listing the set of attributes relevant for the current scenario. Exchange Online includes a horde of other attributes that might be relevant for other object types (such as ExternalEmailAddress/targetAddress for mail user objects), so the above is certainly not an exhaustive list. The important thing is that the same set of information is available within both directories, as shown on the screenshot above.

Here’s also a good place to mention another bit of misinformation I’ve run into, namely that the alias/mailNickname value must match the “alias” part of the Primary SMTP address. As evident from the screenshot above, this is not the case. We’ve also shown above that changing the Group’s mailNickname does not result in updating any part of the Primary SMTP address, and the same holds true when performing this operation via Exchange Online’s methods. In fact, it goes in both directions, as updating the Primary SMTP address attribute does not result in updating mailNickname‘s value.

Finally, let’s review some examples of how you can actually update a Group’s email address in Microsoft 365. The easiest way is via Exchange Online’s Set-UnifiedGroup cmdlet, which allows you to either change the PrimarySMTPAddress directly, or add/remove/replace individual addresses via the EmailAddresses parameter. The examples below were all run against a different Microsoft 365 Group object than the one we used above, just to make sure we don’t cross the streams and affect the outcome of any potential background operations while waiting for magic to happen 🙂

We can use the Set-UnifiedGroup cmdlet and its –PrimarySmtpAddress parameter to configure new Primary SMTP address for the Group, while ensuring that the previous primary alias will be preserved as secondary one (which might be important for mail flow reasons):

#Change the Primary SMTP address for a Microsoft 365 Group. Note that the existing Primary SMTP address will be preserved as secondary alias
Set-UnifiedGroup Team688 -PrimarySmtpAddress abc@michev.onmicrosoft.com

If on the other hand we want to completely replace the existing Primary SMTP address value, or make additional changes to any secondary ones (i.e. add, update or remove existing aliases), we can instead use the Set-UnifiedGroup cmdlet with the –EmailAddresses parameter.

#Add a secondary address for a Microsoft 365 Group
Set-UnifiedGroup Team688 -EmailAddresses @{add="smtp:testing123@michev.info"}

#Add a SIP address (just for the sake of example)
Set-UnifiedGroup Team688 -EmailAddresses @{add="SIP:testing123@michev.info"}

#Remove an existing address
Set-UnifiedGroup Team688 -EmailAddresses @{remove="SIP:testing123@michev.info"}

For additional details and examples, refer to the Set-UnifiedGroup cmdlet’s help. Another method one can use to update the Primary SMTP Address of a Microsoft 365 Group is via the Outlook REST API. As this API is now officially deprecated (after some delay), I will not give specific examples here. I’ll give you a hint though – OWA is still using said API for making changes to Microsoft 365 Groups, so you can just get the required details by hitting F12. And should you need an automated solution, remember that you can connect to Exchange Online PowerShell via certificate-based authentication, or even call the InvokeCommand method outside of PowerShell.

Two more relevant details need to be mentioned. First, Exchange Online will use the default accepted domain for provisioning the Primary SMTP address when creating the Group. You can override this behavior by specifying either the –PrimarySmtpAddress or –EmailAddresses parameters when running the New-UnifiedGroup cmdlet and providing the desired values. In addition, while Exchange Online does not support Email address policies in general, there is an exception for the case of Microsoft 365 Groups. In case you want to configure an Email address policy for Group objects, the details can be found in this article.

Summary

Before closing the article, few thoughts on how we ended up here. The posts I was referring to in the beginning of the article were all from the community forums, and all posted recently. My gut feeling was that those were likely the result of improper guidance by everyone’s favorite AI BS spiller, and sure enough, a quick query resulted in this:

Of course we cannot just blame Copilot on this, as it copied the information from other sources (few SO posts to be precise). Which doesn’t change the fact that the information provided is just plain wrong, as also observed by the people posting such questions online. Oh well.

In summary, we’ve shown that you cannot use the Graph API to make changes to email addresses for Microsoft 365 Groups. Instead, you should be using the Exchange Online Set-UnifiedGroup cmdlet, as such changes need to be performed against ExODS first (the dual-write mechanism will take care of committing them to Azure AD at the same time). We have also provided a reminder that Email address policies can be used for Microsoft 365 Groups, a fact that is often times overlooked.