Distribution List Expansion Guide

ContactMonkey enables customers to target audiences using their existing "To" field, which often contains distribution lists (DLs). Our application leverages Microsoft's APIs to expand these lists and retrieve recipient details. Depending on the type of list your organization uses, either EWS or Graph API is required. The unique members are subsequently used as the mailing list for emails sent with ContactMonkey.

To configure a utility account, you will need:

• Admin or Owner permissions within ContactMonkey.
• An IT administrator who can consent to ContactMonkey's Enterprise Application for either EWS or Graph API.

Refer to the table below to determine the appropriate expansion method for your organization:

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 will need to create a utility account (with at least a P1 license and a working mailbox) with permission to make Graph/EWS API calls.

Note: While it is possible to use an existing utility account to proceed, we strongly recommend creating a dedicated mailbox. This is to ensure your team’s integration with ContactMonkey remains intact even if the owner of the existing account transfers to a different department/organization and their account is deactivated.
2. Grant Admin Consent

Your IT administrator must grant the necessary permissions for the application using one of the links below:

• Grant Consent for Graph Expansion
• Grant Consent for EWS Expansion

Note: Once the permissions are approved, you will be redirected to the ContactMonkey application. If you are not a ContactMonkey user, you may be directed to the login page.

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 into your ContactMonkey Dashboard (US | EU | AU | CA)
2. Click the dropdown arrow next to your name (top-right corner) and select Settings → Integrations.
3. Sign into the utility account (EWS or Graph) using the mailbox created by your IT team.
   • If you do not see the option to sign in, it means you are not a ContactMonkey administrator for your organization - please contact support@contactmonkey.com to update your account role
4. If you have both expansion methods configured, set your preferred default:
   • Click Show Details.
   • Under Default Expansion Method, select either Add-in (EWS) or Utility Account (Graph API):

Note: please make sure you are entering the email address(es) of the distribution list(s) in the field provided in the Test Count section to generate an accurate result.

FAQ

Q: What permissions do I have to grant through the utility account?

• Read directory data - This is referring to the Directory.Read.All scope
• Read all users' full profiles - This refers to the User.Read.All scope

Combining these two permissions allows ContactMonkey to obtain a list of all your tenant lists, such as distribution lists and Office 365 groups, on behalf of the signed-in user. When internal comms personnel use ContactMonkey to send a campaign to specific lists, ContactMonkey obtains the inputted DLs using our Web Add-in. We pass these along and use the email addresses to search through all the lists to obtain each DL's ID. We then use the IDs to expand all the recipients inside the selected lists to obtain the email address for each recipient in the list. We use the email address to count the unique number of recipients in the list, including those in nested lists. Every nested list is expanded until each recipient's email address can be obtained.

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.