How can we help you?

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

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:

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

1. Open the Exchange Admin Center
2. Navigate to Roles → Admin roles
3. Search for and select View-Only Organization Management
4. Click the Assigned tab, search for and add your new Service Account

Learn more about Role-based Permissions on Exchange Online.

1.3 Grant API Permissions

Grant delegated permissions to ContactMonkey's enterprise applications by clicking both links below:

1. Grant Consent for Graph Backend
2. Grant Consent for Exchange Admin Backend using the region your ContactMonkey data is stored in:
   • US Region
   • CA Region
   • EU Region
   • AU Region

What happens after clicking:

• You'll be redirected to Microsoft's consent screen
• Sign in with your Microsoft Admin account credentials
• Review and accept the requested permissions
• After granting, you'll see a success confirmation screen
• You are not required to log into ContactMonkey if you do not have an account

Permissions being granted:

• GroupMember.Read.All - Read the membership of all groups
• User.Read.All - Read all users' profiles
• Exchange.ManageV2 - Manage and expand dynamic distribution lists.
• EWS.AccessAsUser.All - Access mailboxes via Exchange Web Services (EWS only)
  • To be deprecated October 1, 2026

For more information on API permissions, click here: API Permissions and Utility Account Access Explained

1.4 Assign Service Account in Entra Admin Center

1. Open Microsoft Entra Admin Center
2. Navigate to Enterprise Applications
3. Search for ContactMonkey-Utility (Graph Backend app) or ContactMonkey - Exchange Online Admin API (Exchange Admin API Backend app)
4. Click Users and groups → Add user/group
5. Select your service account and assign it
6. Repeat for the other utility app, if applicable

Step 2: Enable Integrations in ContactMonkey

👤 Role: ContactMonkey Administrator

2.1 Access Integration Settings

1. Click your name at the top right of the ContactMonkey dashboard
2. Click Settings
3. 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:

1. Click Sign In
2. Choose one of the following sign-in options:
   • Service account created by your IT team (recommended)
   • Your Microsoft user account
3. 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:

1. Click Show Details in either the Graph or Exchange Admin Utility Account card
2. Under Default Expansion Method, select either:
   • Exchange Admin Backend - Best for dynamic distribution lists
   • Graph Backend - Best for distribution groups with hidden membership
3. 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

1. On the Integrations page, click Show Details on your preferred utility account
2. In the Distribution List field, enter one or more distribution list email addresses (comma-separated)
3. Click Test Count
4. 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

• Click here for diagnostic steps
• You may need to modify the distribution list type
• Consider alternative approaches like CSV upload or List Management

⚠️ Account Shows "Inactive":

• This typically means OAuth tokens have expired
• Running a test count should reactivate the account
• If it remains inactive, sign out and sign back in
• Click here for more details

Success Criteria

Your setup is complete when:

• 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:

1. Open an Incognito or private browsing window
2. Sign in to ContactMonkey with a username and password — not Microsoft SSO
3. 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.