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

ContactMonkey uses EWS (client side) as its expansion method by default. EWS is an excellent choice for customers who are sending to less than 25,000 recipients and not sending to hidden distribution lists.

Expanding via Graph API is required for customers sending to lists greater than 25,000 or hidden distribution lists. It is a more modern method of List Expansion using Microsoft's newer API method.  This process can be achieved by connecting a Utility account to the ContactMonkey App. 

Getting Started

The benefit of using list expansion will vary based on what type of tracking you use:

• Overall: Gives user recipient count in the dashboard (how many people are on the distribution list at send time).
• Individual and anonymous individual: Expands everything in the "To" field and allows us to send individual emails to each person.

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

Your IT team must create a utility account (service account with a license) with access to make the required Microsoft Graph calls.

1. Once an account has been created, contact your account manager or email support@contactmonkey.com so we can enable the feature.  
2. Your IT administrator will need to provide consent to the application. This can be granted on behalf of your organization via this URL.
3. To obtain the technical documentation for your IT team, see the attached PDF at the bottom of this page.

Step 2: Connect The Utility Account In ContactMonkey Settings

Once the utility account is created with the correct permissions, you will need to connect it to your ContactMonkey account by following these steps:

1. Sign in to your ContactMonkey dashboard
2. Select the down arrow next to your name in the top right to open the main menu
3. Select Settings
4. Click Integrations in the menu on the far left
5. In the Utility Account tile, select Sign In
6. Sign in using OAuth2.

Step 3: Select Your Default Expansion Method In The Add-In

The final step is to ensure that your expansion method has been selected within your ContactMonkey Add-in in Outlook. Note: These steps will vary slightly based on which version of Outlook you are using.

To do so, follow these steps:

1. Launch your Outlook account
2. Create a New Message
3. Click the ContactMonkey icon to open the add-in
4. Click the gear icon in the top-right
5. Under the Default expansion method, select your chosen method.

Step 4 (optional): Set Your Default Expansion Method From The ContactMonkey Dashboard

To set your default expansion method from the ContactMonkey Dashboard, your account must have the Administrator role.

1. Log in to your ContactMonkey account 
2. Click on your display name in the top right-hand corner 
3. Select Settings from the drop-down list 
4. Select Integrations from the options on the left 
5. Under Utility Account, select Show Details 
6. Under Default Expansion Method, select either EWS or Utility Account (Graph API)
7. Click on Close

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 EWS or 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
   
   
   1. 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.
   2. Add a Subject to the Email (e.g., Test)
2. Open the ContactMonkey AddIn within the Email Message
   
   
   1. Click on the Count Recipients section.  This will start the process of ContactMonkey using the selected API (EWS or Graph) 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.
   2. 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
   3. If the information presented is not as expected, customers should look at switching the API to the other Default Expansion Method
   4. If neither result produces the expected results, 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 before utilizing the method.  Please note that customers can only test the Graph API results.  

1. Log in to the region where your ContactMonkey data is being hosted: https://contactmonkey.com/users/sign_in?layout=desktop
2. Go to your Settings section.  In the Upper Right corner where your name is displayed, click on it, and Select Settings.
   
3. Select Integrations in the left menu and under the Utility Account, select Show Details
   
   
4. In the Window that pops up, you can then add the distribution list to the field and click on Test Count