Setting Up Distribution List Expansion

Distribution list expansion allows ContactMonkey to retrieve individual recipient details from your Outlook distribution lists, enabling accurate tracking and recipient counting.

Time to complete: 20-30 minutes

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
• Entra P1 license available for a service account

Best practice: We recommend enabling both Graph Backend and EWS Backend 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: Entra P1 or higher
• 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 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 EWS Backend

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

Permissions being granted:

• Directory.Read.All - Read directory data
• User.Read.All - Read all users' profiles
• EWS.AccessAsUser.All - Access mailboxes via Exchange Web Services (EWS only)

Learn more about these permissions here.

1.3 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 EWS-Utility (EWS 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 EWS Utility Account.

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 EWS Utility Account card
2. Under Default Expansion Method, select either:
   • EWS 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 EWS 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)

Frequently Asked Questions

Q: Do I need both Graph and EWS Backend 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: EWS Backend 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.