How can we help you?

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.

1. Ask your IT team to confirm the DL's type in Microsoft 365 Admin Center
2. Compare against the compatibility matrix in Distribution List Types and Expansion Support

Step 2: Double-check Utility Account Integrations (Admin Only)

1. Click your name at the top right of the ContactMonkey dashboard
2. Click Settings → Integrations
3. Verify that all utility account tiles are active (refer to this article if anything needs to be activated)
4. Once connected, click Show Details for each tile and run a test count

Step 3: 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 connected to the utility account tile(s) has permission to read the list membership

Solutions

Solution A: Switch Expansion Methods (Admin Only)

• Change your default expansion method to the one that supports your list type

Solution B: Modify the Distribution List (IT Only)

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-premises 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 (Admin Only)

1. Go to Settings → Integrations
2. Click Show Details on the inactive utility account
3. Enter any distribution list email in the Distribution List field
4. Click Test Count
5. The account should automatically reactivate

Solution B: Sign Out and Sign Back In 

If Test Count doesn't reactivate the account:

1. Click Show Details on the inactive utility account
2. Click Sign Out
3. Click Sign In again
4. Authenticate with the same credentials
5. The account should now show as Active

Solution C: Verify Service Account Status

If signing back in fails:

1. Confirm the service account still exists in Microsoft 365
2. Verify the account hasn't been disabled or deleted
3. Check that the account's license is still active
4. 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 Exchange Online Admin should expand nested lists, but deeply nested structures can cause issues.

1. Verify the list structure in Microsoft 365
2. Check if nested lists exceed 10 levels deep
3. Try flattening the list structure if possible

Step 3: Verify Hidden Membership

If your list has hidden membership:

• Graph Backend: Should work ✅
• EOA Backend: Will not work ❌

Switch to Graph Backend if you need to expand hidden membership lists.

Solutions

Solution A: Use CSV Upload 

Export recipients from Microsoft 365 and upload as a CSV.

Solution B: 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 EOA APIs.
• Permission Issues. The service account may lack permission to access the list.
• EOA Invalid Recipient. EOA API cannot expand a distribution list if there's an invalid or unresolvable email address within it.

Solutions

Solution A: Verify Cloud vs On-Premise

1. Check where your distribution list is hosted
2. If it's on-premise, work with IT to migrate it to Microsoft 365 cloud
3. Cloud-hosted lists are fully supported

Solution B: Check List Type Compatibility

1. Review Distribution List Types and Expansion Support
2. Compare your list type against the compatibility matrix
3. Convert to a supported list type if possible

Solution C: Verify Service Account Permissions

1. Ensure the service account has been assigned to both enterprise applications
2. Verify the account has an active mailbox
3. Check that consent was granted for all required permissions
4. 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