Skip to main content
  1. ContactMonkey Help Center
  2. Integrations
  3. Distribution List Expansion

API Permissions and Utility Account Access Explained

When you set up distribution list expansion, ContactMonkey requests specific API permissions from Microsoft 365. This article explains what each permission does, why it's needed, and what data ContactMonkey accesses.

Permissions Summary

ContactMonkey requests three delegated permissions:

  • Directory.Read.All
  • User.Read.All
  • EWS.AccessAsUser.All

🔐 Security Note: These are delegated permissions, not application permissions. Actions are performed on behalf of the signed-in service account, not autonomously by the application.

Why Each Permission Is Required

Directory.Read.All

What it allows:

  • Read list of all distribution lists in your tenant
  • Access Office 365 group information
  • Retrieve security group details
  • View group membership structure

What ContactMonkey does with it:

  1. When a user enters a distribution list in the To field, ContactMonkey receives the list's email address
  2. ContactMonkey uses this permission to search your directory for that list
  3. Once found, ContactMonkey retrieves the list's unique ID

What ContactMonkey does NOT do:

  • Modify directory data
  • Create or delete groups
  • Change group memberships
  • Access sensitive directory information unrelated to distribution lists

Data flow:

User enters: sales-team@company.com
    ↓
ContactMonkey searches directory
    ↓
Finds list ID: aaaa-bbbb-cccc-dddd
    ↓
Uses ID for expansion

User.Read.All

What it allows:

  • Read user profile information
  • Access user email addresses
  • View basic user properties (name, title, department)

What ContactMonkey does with it:

  1. After identifying the distribution list, ContactMonkey retrieves list members
  2. For each member, ContactMonkey accesses their email address
  3. If the member is a nested list, ContactMonkey repeats the expansion process
  4. Email addresses are used to count unique recipients and track engagement

What ContactMonkey does NOT do:

  • Access user passwords or credentials
  • Read user mailbox contents
  • Modify user profiles
  • Access sensitive personal information beyond basic profile data

Data flow:

Distribution List "Sales Team" contains:
    ↓
Member 1: user1@company.com
Member 2: user2@company.com
Nested List: "Regional Managers"
    ↓
ContactMonkey expands nested list
    ↓
Gets: user3@company.com, user4@company.com
    ↓
Final count: 4 unique recipients

EWS.AccessAsUser.All (EWS Backend Only)

What it allows:

  • Access Exchange Web Services API
  • Perform mailbox operations on behalf of the signed-in user
  • Read folder structures and item metadata

What ContactMonkey does with it:

  1. Connects to Exchange Web Services using the service account credentials
  2. Expands distribution lists that Graph API cannot handle (dynamic lists)
  3. Retrieves recipient email addresses from expanded lists

What ContactMonkey does NOT do:

  • Read email message content
  • Send emails on behalf of users
  • Modify mailbox items
  • Access calendar or contact data

📝 Note: This permission is only requested for EWS Backend. If you only enable Graph Backend, this permission is not required.

How ContactMonkey Uses These Permissions

Complete Data Flow

Here's what happens when a user sends a tracked email to a distribution list:

Phase 1: List Identification

  1. User composes email in Outlook and enters distribution list in To field
  2. ContactMonkey Add-in captures the list email address
  3. Using Directory.Read.All, ContactMonkey searches your tenant's directory
  4. ContactMonkey identifies the list and retrieves its unique ID

Phase 2: List Expansion

  1. Using the list ID, ContactMonkey retrieves list members
  2. For each member, ContactMonkey uses User.Read.All to get their email address
  3. If a member is on another list (nested), ContactMonkey repeats steps 3-6
  4. ContactMonkey continues until all nested lists are fully expanded

Phase 3: Recipient Processing

  1. ContactMonkey counts unique email addresses (removing duplicates)
  2. Displays recipient count to the user before sending
  3. User reviews count and proceeds with sending
  4. Email is sent with tracking enabled
  5. Recipient email addresses are stored for engagement tracking (opens, clicks)

What Data Leaves Your Infrastructure

Data sent to ContactMonkey servers:

  • Distribution list email addresses (e.g., sales@company.com)
  • Individual recipient email addresses from expanded lists
  • Engagement data (opens, clicks, timestamps)
  • Basic sender information (name, email)

Data that stays in your infrastructure:

  • Email message content
  • Attachments
  • User credentials
  • Directory structure beyond list memberships
  • Full user profiles (only email addresses are extracted)

Updated_diagram.png

Security Considerations

Delegated vs Application Permissions

ContactMonkey uses delegated permissions, which means:

  • Actions are performed as the signed-in service account
  • Permissions are limited by the service account's own permissions
  • If the service account cannot access a resource, ContactMonkey cannot either
  • Audit logs show actions as performed by the service account

Why this matters: Using a basic user account as your service account limits ContactMonkey's access to only what a standard user could access. This follows the principle of least privilege.

Service Account Best Practices

Recommended configuration:

  • Create a dedicated service account (not a personal account)
  • Assign the minimum license required (P1)
  • Use a strong, unique password stored in a password manager
  • Name the account clearly (e.g., contactmonkey-service@company.com)
  • Document the account in your IT asset inventory

Do NOT:

  • Share the service account credentials broadly
  • Use SMS-based MFA (use an authenticator app instead)
  • Grant the account higher permissions than necessary

Audit and Compliance

Monitoring service account activity:

  • All API calls appear in Microsoft 365 audit logs
  • Actions are logged as performed by the service account
  • You can review access patterns in Microsoft Entra sign-in logs
  • Unusual activity can be detected through your existing security monitoring

Revoking access: If you need to revoke ContactMonkey's access:

  1. Remove the service account from the enterprise applications in Entra Admin Center
  2. Disable the service account in Microsoft 365
  3. ContactMonkey will no longer be able to expand distribution lists
  4. Existing tracking will continue to function (stored data)

Frequently Asked Questions

Q: Can ContactMonkey read my users' emails?
A: No. ContactMonkey only accesses distribution list memberships and email addresses. It does not read message content, calendar items, or contacts.

Q: What happens if the service account is disabled?
A: Distribution list expansion will stop working immediately. Any ContactMonkey admin can re-enable it by signing in with another account. Existing tracking data remains intact.

Q: Can we restrict which distribution lists ContactMonkey can access?
A: The permissions are tenant-wide. However, ContactMonkey only attempts to expand lists that users explicitly enter in the To field. It does not proactively scan or enumerate all distribution lists.

Q: Does ContactMonkey store our distribution list structure?
A: No. ContactMonkey only retrieves list membership when a user sends an email to that list. We do not cache or store your directory structure.

Q: What if Microsoft changes their API?
A: ContactMonkey actively monitors Microsoft API changes and updates our integration accordingly. Changes are tested in our staging environment before deployment to production.

Was this article helpful?