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 to accurately capture tracking data.
| Both EWS and Graph Backend should be enabled for the best experience |
To complete this process, you will need:
- An IT administrator who can consent to ContactMonkey's Enterprise Application for EWS and Graph API
- Admin or Owner permissions within ContactMonkey
This table provides information on the distribution lists supported by each API:
| Type of List/Group | Graph | EWS |
| Static Distribution Lists | ✅ Supported | ✅ Supported |
| Mailbox Contact Group | ✅ Supported | ✅ Supported |
| Security Group | ✅ Supported | ✅ Supported |
| Universal Group | ✅ Supported | ✅ Supported |
| Dynamic Exchange Group | ❌ Not Supported | ✅ Supported |
| O365 Dynamic Group | ❌ Not Supported | ✅ Supported |
| O365 Group | ✅ Supported | ✅ Supported |
| Distribution Groups with Hidden Membership | ✅ Supported | ❌ Not Supported |
Note: Expansion may not be supported for distribution lists hosted on-premise. To be sure your lists are supported, we always suggest you test the recipient count before sending (step 3).
Step 1: Configure a Service Account
| This step should be completed by an IT Administrator |
a) Create a service account with a mailbox that can make Graph and EWS API calls
Note: While it is possible to assign an existing user account to proceed, we strongly recommend creating a dedicated utility account. This is to ensure your team’s integration with ContactMonkey remains active throughout any departmental changes.
b) Use the service account to grant permission
Please grant delegated permissions to the applications using both of the links below:
You will be redirected to the ContactMonkey application after successfully granting consent to Graph Backend. If you do not have a ContactMonkey account, you will be directed to the login page. You do not need to log in if you do not have a ContactMonkey account.
You will see the following success screen after successfully granting consent to EWS Backend:
c) Assign the service account to the applications in Entra Admin Center
Step 2: Turn on the Integrations in ContactMonkey Settings
| This step should be completed by a ContactMonkey Administrator |
a) Sign into your ContactMonkey Dashboard (US | EU | AU | CA)
b) Click the dropdown arrow next to your name (top-right corner) and select Settings → Integrations
c) Sign into Graph Utility Account and EWS Utility Account with one of the following options:
- The service account created by your IT team (recommended)
- Your Microsoft user account (Note: the integration will break if this profile is deactivated but can be re-enabled right away with another user account)
d) Set your preferred default:
- Click Show Details
- Under Default Expansion Method, select either EWS - Backend or Graph - Backend:
Note: Users will also be able to change their default expansion method on an individual level in their Add-in settings if needed:
Step 3: Verify That the Expansion Methods are Properly Integrated
| This step should be completed by a ContactMonkey Administrator |
a) Click Show Details of your desired utility account
b) Enter the email address(es) of the distribution list(s) in the Distribution List field
c) Click Test Count
An accurate recipient count confirms that the expansion methods are properly integrated.
Infrastructure Diagram
The following diagram illustrates the flow of an email that is sent through EWS or Graph Backend and provides details on where recipient data is going, how it's being used to run ContactMonkey's sending process, and what is leaving your infrastructure.
FAQ
Q: What additional permissions do I have to grant through the utility account?
- Read directory data - This refers to the Directory.Read.All scope
- Read all users' full profiles - This refers to the User.Read.All scope
- Access mailboxes as the signed-in user via Exchange Web Services - This refers to EWS.AccessAsUser.All scope (applicable only to EWS Backend)
Combining these 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 distribution lists using our Web Add-in. We pass these along and use the email addresses to search through all the lists to obtain each list'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.
Q: I already extended my EWS token, do I have to action anything?
The release of EWS Backend replaces the EWS token as the preferred long-term solution for expanding dynamic distribution lists. Please work with your IT team to integrate a utility account with both expansion methods as soon as possible.
Q: Can I enable multi-factor authentication for the utility account?
Yes, but do make sure to sign into the utility account with an MFA authenticator app. Once the account is integrated with ContactMonkey, it will continue to run in the background and shouldn't interfere with normal daily operations on the app. The only other instance where your IT team will need to authenticate again would be if someone turned off the integration in their ContactMonkey settings and reactivated it.
Q: Why is it showing as Inactive?
If your EWS or Graph Utility Accounts are showing as "Inactive" even though you have signed in with your account, it is usually because OAuth tokens from Microsoft expire after some time, and we don't actively keep refreshing them unless they are used. When you run the Test Count the card should appear as "Active" again. You can disregard the "Inactive" status as it will not impact the functionality if an account is signed in.