List Expansion: EWS vs Graph Utility Account, Improving Recipient Count Accuracy

Note: please refer here if your teams are using Dynamic Distribution Lists. It is strongly recommended that your team extends your EWS token before February 17th, 2025 to avoid any interruption in service.

If you do not use Dynamic Distribution Lists, you can switch your expansion method to use Graph API by following the steps below. Please also reach out to support@contactmonkey.com if you choose to move in this direction.

To configure a utility account, you will need:

• Admin or Owner permissions within ContactMonkey.
• An IT administrator who can consent to ContactMonkey through Microsoft Graph API.

Supported List Types

Below are the supported list types:

Note: Expansion may not be supported for distribution lists that are hosted on-premise.

To be sure your lists are supported, we always suggest you "test" the count before sending. 

Step 1: Configure the Utility Account

1. Create a utility account with a mailbox

Your IT team must create a utility account (ex: contactmonkey-util@<yourdomain>.com, a service account with a P1 license and a working mailbox will suffice) with permissions to make Graph API calls.

2. Grant Admin Consent

Your IT administrator must grant the necessary permissions for the application using this link.

3. Assign the User to the Application

Ensure the utility account (ex: contactmonkey-util@<yourdomain>.com) is assigned to the ContactMonkey application.

Step 2: Connect the Utility Account in ContactMonkey Settings

Once the utility account is created with the correct permissions, link it to your ContactMonkey account:

1. Sign in to the ContactMonkey dashboard
2. Click the dropdown arrow next to your name (top-right corner) and select Settings → Integrations.
3. Sign in to the utility account using the mailbox created by your IT team.
4. Set the expansion method as your default:
   • Click Show Details.
   • Under Default Expansion Method, select Utility Account (Graph API)
     
5. Test the configuration by entering a distribution list in the input field.

Step 3: Select Your Default Expansion Method in the ContactMonkey Add-In

To complete the setup, configure the expansion method within the ContactMonkey Outlook Add-in:

1. Open Outlook.
2. Create a New Message.
3. Click the ContactMonkey icon to launch the add-in.
4. Click the gear icon in the top-right corner.
5. Under Default Expansion Method, select Utility Account (Graph API).

Testing Count Lists

Customers can test their counts using a variety of methods.  This can help customers identify if a list will be countered properly with Graph API and if the data is accurate. These tests do not require a test email to be sent.

Testing in the ContactMonkey Add-In for Outlook

Customers utilizing the Add-in (For Classic Outlook, Modern Outlook, and Outlook Web Application [OWA]) can test it within the Outlook Add-In.  

1. Open Outlook or OWA and create a new email
   
   • Add the Distribution List(s) to the To: field you want to test (e.g. DL-Customer Success).  Feel free to add and test them one at a time if needed.
   • Add a Subject to the Email (e.g., Test)
2. Open the ContactMonkey AddIn within the Email Message
   
   
   • Click on the Count Recipients section.  This will start the process of ContactMonkey using Graph API to check if it can see the recipients in the Distribution Lists.  Please note that this process may take some time, depending on the size of the recipients.
   • Customers can then click on the link for the # of recipients (The five recipient(s) link in the example) and see the recipients that were/were not counted and any mail merge fields utilized in the email
   • If the information presented is not as expected, customers should contact their internal IT team to discuss changing the attributes of the existing distribution lists or adding their contact list to the ContactMonkey Dashboard Directory via List Management.
3. Once testing is completed, users can send emails confidently knowing how the recipients and metrics will be calculated.

Testing in the ContactMonkey Dashboard

Customers can test the Graph API set up within the ContactMonkey Dashboard. Please ensure the Utility account is set up beforehand. 

1. Log in to the region where your ContactMonkey data is being hosted: https://contactmonkey.com/users/sign_in?layout=desktop
2. Click on your name at the top righthand corner and select Settings:
   
3. Select Integrations in the left menu and under Utility Account, select Show Details:
   
   
4. In the window that pops up, enter the email address(es) of your desired distribution list(s) in the field and click on Test Count:
   

You're All Set! 🎉

Your distribution lists will now expand correctly based on your selected method. If you encounter any issues, contact your IT team or ContactMonkey support.