Skip to main content

How can we help you?

Search

Troubleshooting Distribution List Expansion

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. Check your list type in Microsoft 365 Admin Center
  2. Compare against the compatibility matrix in Distribution List Types and Expansion Support

Step 2: Check Which Expansion Method You're Using

  1. Open Outlook and create a new message
  2. Open the ContactMonkey Add-in
  3. Click the gear icon above Send & Track
  4. Note which method is selected in the Default expansion method section

If using Graph Backend:

  • Switch to Exchange Online Backend if your list is a dynamic distribution list
  • Graph does not support dynamic lists
  • Graph does not count shared mailboxes

If using Exchange Online Backend:

  • Switch to Graph Backend if your list has hidden membership
  • Exchange Online Admin does not support O365 dynamic groups or O365 groups

Note: Dynamic lists that contain hidden members are not supported by either expansion method.

Step 3: Retest with the Alternative Method

  1. Click Count Recipients in the Add-in
  2. 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
  • 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

  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 EWS 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 ✅
  • 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.

EWS Invalid Recipient

EWS 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

Related articles