This guide helps you diagnose and resolve common issues with distribution list expansion in ContactMonkey. If you haven't set up expansion yet, start here.
Issue 1: Inaccurate Recipient Count
Symptoms
- Test count returns one recipient
- Count is lower than expected
- Count doesn't match the actual list membership
Diagnostic Steps
Step 1: Verify the Distribution List Type
Not all distribution list types are supported by both expansion methods.
- Check your list type in Microsoft 365 Admin Center
- Compare against the compatibility matrix in Distribution List Types and Expansion Support
Step 2: Check Which Expansion Method You're Using
- Open Outlook and create a new message
- Open the ContactMonkey Add-in
- Click the gear icon above Send & Track
- Note which method is selected in the Default expansion method section
If using Graph Backend:
- Switch to EWS Backend if your list is a dynamic distribution list
- Graph does not support dynamic lists
- Graph does not count shared mailboxes
If using EWS Backend:
- Switch to Graph Backend if your list has hidden membership
- EWS cannot expand hidden membership groups
Note: Dynamic lists that contain hidden members are not supported by either expansion method.
Step 3: Retest with the Alternative Method
- Click Count Recipients in the Add-in
- An accurate count means that the expansion method you selected supports your list
Step 4: Verify List Configuration in Microsoft 365
Check these common misconfigurations:
- List is nested too deeply: Some nested structures may cause expansion issues
- List contains external recipients: Graph Backend has limitations with external recipients when using the To field. See Issue 3 below
- Permissions issues: Ensure the service account has permission to read the list membership
Solutions
Solution A: Switch Expansion Methods
- Change your default expansion method to the one that supports your list type
- Each user can also set their own preference in the Contactmonkey Add-in settings
Solution B: Modify the Distribution List
If neither method works:
- Convert the list to a supported type
- Unhide a hidden membership list (if security policies allow)
- Move the list from on-premise to cloud-hosted
Solution C: Use Alternative Approaches
If you cannot modify the list:
-
CSV Upload: Export list members and upload as a CSV file
- See How to Upload a CSV File in Outlook 365
- Provides individual tracking without API-based expansion
-
List Management: Use ContactMonkey's built-in List Management feature
- Manage recipients independently of Microsoft 365 lists
Issue 2: Utility Account Showing Inactive
Symptoms
- Integration card(s) display Inactive status
- Previously working expansion stops functioning
- Cannot count recipients in the Add-in
Cause
OAuth tokens issued by Microsoft expire after a period of inactivity. This is normal Microsoft 365 security behavior.
Solutions
Solution A: Reactivate by Running Test Count
- Go to Settings → Integrations
- Click Show Details on the inactive utility account
- Enter any distribution list email in the Distribution List field
- Click Test Count
- The account should automatically reactivate
Solution B: Sign Out and Sign Back In
If Test Count doesn't reactivate the account:
- Click Show Details on the inactive utility account
- Click Sign Out
- Click Sign In again
- Authenticate with the same credentials
- The account should now show as Active
Solution C: Verify Service Account Status
If signing back in fails:
- Confirm the service account still exists in Microsoft 365
- Verify the account hasn't been disabled or deleted
- Check that the account's license is still active
- Ensure the account password hasn't expired
Prevention
- Use a dedicated service account (not a personal account) to avoid deactivation during personnel changes
- Ensure the service account has password expiration policies that won't cause lockouts
- Document the service account credentials securely for your IT team
Issue 3: Missing Recipients
Symptoms
- Some recipients don't appear in tracking data
- External recipients are not being tracked
- Nested list members are missing
Diagnostic Steps
Step 1: Check Recipient Type
External Recipients: External recipients have different support depending on your setup.
Step 2: Check Nested Lists
Both Graph and EWS should expand nested lists, but deeply nested structures can cause issues.
- Verify the list structure in Microsoft 365
- Check if nested lists exceed 10 levels deep
- Try flattening the list structure if possible
Step 3: Verify Hidden Membership
If your list has hidden membership:
- Graph Backend: Should work ✅
- EWS Backend: Will not work ❌
Switch to Graph Backend if you need to expand hidden membership lists.
Solutions
Solution A: Switch Expansion Method
Based on your diagnostic findings, switch to the appropriate method in the Add-in.
Solution B: Use CSV Upload
Export recipients from Microsoft 365 and upload as a CSV.
Solution C: Adjust List Configuration
Work with your IT administrator to:
- Unhide hidden membership (if security allows)
- Reduce nesting depth
- Separate external recipients into a different list
Issue 4: List Cannot Be Expanded
Symptoms
- Error message when attempting to expand
- "We encountered an issue while attempting to expand the recipients in the To field" email alert
- Test Count fails completely
Common Causes
On-Premise Distribution Lists
Lists hosted on on-premise Exchange servers may not be accessible via Microsoft's Graph or EWS APIs.
Unsupported List Type
Your list may be a type that neither Graph nor EWS can expand (i.e. dynamic list with hidden members)
Permission Issues
The service account may lack permission to access the list.
Solutions
Solution A: Verify Cloud vs On-Premise
- Check where your distribution list is hosted
- If it's on-premise, work with IT to migrate it to Microsoft 365 cloud
- Cloud-hosted lists are fully supported
Solution B: Check List Type Compatibility
- Review Distribution List Types and Expansion Support
- Compare your list type against the compatibility matrix
- Convert to a supported list type if possible
Solution C: Verify Service Account Permissions
- Ensure the service account has been assigned to both enterprise applications
- Verify the account has an active mailbox
- Check that consent was granted for all required permissions
- See API Permissions and Utility Account Access Explained
Solution D: Use Alternative Methods
If the list truly cannot be expanded:
- CSV Upload: Manually export and upload recipients
- List Management: Create a managed list in ContactMonkey
- Segment your audience: Use multiple smaller lists instead