Distribution list expansion allows ContactMonkey to retrieve individual recipient details from your Outlook distribution lists, enabling accurate tracking and recipient counting.
What You'll Accomplish
By completing this setup, you'll enable:
Accurate recipient counting for distribution lists before sending
Individual tracking for campaigns sent to distribution lists
Support for multiple list types
Prerequisites
Before you begin, ensure you have:
IT Administrator access to grant consent in Microsoft Entra Admin Center
ContactMonkey Administrator or Owner permissions in your ContactMonkey account
Exchange Online Plan 1 or 2 license available for a service account
Best practice: We recommend enabling both Graph Backend and Exchange Admin for maximum compatibility with different list types. Click here to understand which API works with your lists.
Step 1: Create and Configure Service Account
👤 Role: IT Administrator
1.1 Create the Service Account
Create a dedicated Microsoft 365 service account with these specifications:
License required: Exchange Online Plan 1 or 2
Mailbox: Must have an active, working mailbox
Role: Can be assigned as a basic user
Naming convention: Use a descriptive name like contactmonkey-service@yourcompany.com
⚠️ Important: While you can use an existing user account, we strongly recommend creating a dedicated service account. This ensures your ContactMonkey integration remains active during employee transitions, role changes, or account deactivations.
1.2 Assign View-Only Exchange Role
Before granting API access, you must ensure the service account has read-only access to Exchange data.
Search for ContactMonkey-Utility (Graph Backend app) or ContactMonkey - Exchange Online Admin API (Exchange Admin API Backend app)
Click Users and groups → Add user/group
Select your service account and assign it
Repeat for the other utility app, if applicable
Step 2: Enable Integrations in ContactMonkey
👤 Role: ContactMonkey Administrator
2.1 Access Integration Settings
Click your name at the top right of the ContactMonkey dashboard
Click Settings
Click Integrations
2.2 Connect Your Utility Accounts
You'll see two integration cards: Graph Utility Account and Exchange Admin Backend. Note that EWS Utility Account will be deprecated October 1, 2026.
For each integration:
Click Sign In
Choose one of the following sign-in options:
Service account created by your IT team (recommended)
Your Microsoft user account
Complete the Microsoft authentication flow
⚠️ Warning: If you sign in with your personal Microsoft account instead of the service account, the integration will stop working if your account is deactivated. However, any ContactMonkey admin can quickly re-enable it by signing in again with another account.
2.3 Set Default Expansion Method
If both accounts are connected:
Click Show Details in either the Graph or Exchange Admin Utility Account card
Under Default Expansion Method, select either:
Exchange Admin Backend - Best for dynamic distribution lists
Graph Backend - Best for distribution groups with hidden membership
Your selection will automatically be applied to new users
💡 Tip: Individual users can override this default in their Outlook Add-in settings if they need different expansion behavior for specific campaigns.
Step 3: Verify Expansion is Working
👤 Role: ContactMonkey Administrator
3.1 Run a Test Count
On the Integrations page, click Show Details on your preferred utility account
In the Distribution List field, enter one or more distribution list email addresses (comma-separated)
Click Test Count
Results will be emailed to you
3.2 Interpret Results
✅ Success: The recipient count matches your expected number
Your expansion is configured correctly
All users in your organization can now send tracked emails to distribution lists
❌ Inaccurate Count: The number doesn't match expectations
Both Graph Backend and Exchange Admin Backend show as Active in ContactMonkey
Test Count returns accurate recipient numbers for your distribution lists
Users can see recipient counts when composing emails with distribution lists in Outlook's To field
Tracking data captures individual recipient interactions (opens, clicks)
Troubleshooting
Utility Account Tile Shows the Wrong Email Address
After you sign into a utility account with your service account credentials, the tile displays your own email address instead of the service account's. For example, you sign in as contactmonkey-service@yourcompany.com but the tile shows your own admin address.
Cause: If you are signed into ContactMonkey with Microsoft SSO, your browser session is linked to your own Microsoft user profile. That session automatically signs you into the utility account as yourself, rather than the service account you entered.
To confirm the service account connects correctly:
Open an Incognito or private browsing window
Sign in to ContactMonkey with a username and password — not Microsoft SSO
Sign in to the utility account with your service account credentials
Because Incognito does not carry over your SSO session, this confirms whether the service account resolves correctly on its own.
Note: Use Incognito only for this test. Connect the integration for regular use while off Incognito.
Frequently Asked Questions
Q: Do I need both Graph and Exchange Admin enabled? A: We recommend enabling both for maximum compatibility. Different list types work better with different APIs. Click here for the complete compatibility matrix.
Q: What if I already extended my EWS token? A: Exchange Admin replaces the legacy EWS token extension as our long-term solution. Please complete this setup to ensure continued support for dynamic distribution lists.
Q: Can the service account have multi-factor authentication enabled? A: Yes. Use an MFA authenticator app (not SMS/email) during initial sign-in. Once integrated, the utility account runs in the background without requiring repeated authentication. You'll only need to authenticate again if someone disables and re-enables the integration in Settings.
Q: What if my distribution lists are hosted on-premise? A: On-premise distribution lists may not be supported by our expansion methods. Run a test count to verify. If expansion fails, consider using CSV upload or List Management as alternatives.
Q: Why is EWS being depreciated? A: Microsoft is retiring Exchange Web Services (EWS) because it is a 20-year-old legacy protocol that no longer meets modern security and performance standards. This is a Microsoft decision, and the effects are industry-wide. Luckily, Exchange Admin Backend was provided by Microsoft to fill in any gaps from the EWS removal.
