Customizing Address Lists and Address Book Policies in Office 365

Use Case:

I’ve been working with a client on a large Office 365 migration. In the course of this migration, many smaller agencies with their own Exchange Organizations are being consolidated into one Office 365 tenant, but these agencies will remain autonomous units to themselves. As a result, the Global Address List contained thousands of users from all agencies. The requirement was given that each agency have access to the Global Address List including all users in the tenant, and also customized address lists with agency specific users and resources.

The Address Book Policy determines what address lists a user sees in their Outlook or OWA. When a new mailbox is created, the “AddressBookPolicy” attribute is empty. Without an  Address Book Policy specified, the user will see all available address lists in the Exchange Online tenant. If no address lists have been created, the user will see these address lists with no address book policies specified:


To change the address lists visible to the user, follow the steps below.


  1. Connect to Exchange Online Powershell. I recommend using Powershell ISE in most cases, and especially this one because you will have to tweak the commandlets to make sure your filter is pulling in the correct objects.
  2. Create the recipient filter for the new address list or lists you want to appear to the user. To develop the filter, I use the get-recipient commandlet before I create the address list. For example, the following will pull all the mailboxes with “IT” in the department field:

Get-Recipient -Filter “((RecipientType -eq ‘UserMailbox’) -and (Department -eq ‘IT’))”

This example is pretty simple. Depending on the requirement for the list, the filter could get very complex and long. There are a lot of combinations of attributes and operators that can be used in combination to pull back the desired objects. Far too many to mention in this post. See Microsoft’s documentation on this topic for a full explanation of the potential recipient filter configuration. Whatever attribute and operator configuration you use, test it using the get-recipient commandlet and adjust it until the get-recipient commandlet outputs the desired objects. This is where it is very helpful to use the Powershell ISE to easily change the filter configuration and perform tests.

3. Once you have your filter configured correctly, You will create the new address list using the New-AddressList commandlet. This example will create a new address list called “IT Users”, that contains all users with that have “IT” in their “Department” field:

New-AddressList “IT Users” -RecipientFilter “((RecipientType -eq ‘UserMailbox’) -and (Department -eq ‘IT’))”

4. Now that we have the new address list, we can create an address book policy that includes the new list, and any combination of the other lists available in the tenant. To do this, user the New-AddressBookPolicy commandlet. The following example creates a address book policy called IT Department. This policy includes all of the default lists in the tenant, and adds the newly configured IT Users list.

New-AddressBookPolicy “IT Department” -AddressLists “\IT Users”, “\All Groups”, “\All Users”, “\All Distribution Lists”, “\All Contacts”, “\Public Folders” -RoomList “\All Rooms” -GlobalAddressList “\Default Global Address List” -OfflineAddressBook “\Default Offline Address Book”

5. Apply the address book policy to the needed users. This can be done in any number of ways. To do this to an individual mailbox, you can use the Exchange Admin Center and adjust the “Address book Policy” field on the “Mailbox features” tab for that mailbox. To this in bulk, you can use the Set-Mailbox commandlet and set the AddressBookPolicy attribute to the needed policy. (ex: IT Department). I have used something like following line to pull back certain users, and apply an address book policy. Adding the “verbose” switch simply allows me to monitor the progress and accuracy of the script.

Get-User -Filter “((Department -eq ‘IT’) -and (RecipientType -eq ‘UserMailbox’))” -ResultSize Unlimited | Set-Mailbox -AddressBookPolicy “IT Department” -Verbose

Final Note:

There is a quirk in Exchange Online that adds one more step to this process. The quirk is that there is no “Update-AddressList” commandlet in Exchange Online like there is in Exchange on premises versions. So to get your new list to populate as you expect, you may need to make a slight change to the object that needs to be in the list, to get the list to include it. This is strange I know, but here is the Microsoft documentation around this limitation. See the “Update an address list” section.

There is a great script called Tickle Mail Recipients that works around this issue in bulk. I have used this a number of time in the past and it works well. The only warning I would give, is that in a large tenant, this script take a very long time to run.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s