Skip to main content

How can we help you?

Search

API Permissions and Service 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:

  • GroupMember.Read.All
  • User.Read.All
  • Exchange.ManageV2
  • EWS.AccessAsUser.All - legacy permission, to be deprecated by Microsoft on October 1, 2026. Read more at the blog post here.

🔐 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

GroupMember.Read.All

What it allows:

  • Read group membership data
  • Get individual recipient email addresses from groups
  • Access nested group memberships

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. This allows ContactMonkey to read group membership information

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 within existing groups using an ID
    ↓
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 the 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

Exchange.ManageV2

What it allows:

  • Access to modern, REST-based Exchange administrative endpoints.
  • The ability to execute specific "Get-" cmdlets (like Get-DistributionGroupMember) via the Exchange Online Admin API.
  • Long-term compatibility with Microsoft's 2026 infrastructure (the successor to EWS).

What ContactMonkey does with it:

  • Identifies and expands membership for Dynamic Distribution Lists and groups that are not supported by the Graph API.
  • Safely retrieves accurate recipient counts for query-based groups when you hit "Send."
  • Maintains a stable connection to your Exchange directory without relying on legacy protocols.

What ContactMonkey does NOT do:

  • Modify your Exchange configuration or tenant settings.
  • Read, move, or delete any email messages in your users' mailboxes.
  • Access administrative areas unrelated to group and mailbox metadata (such as transport rules or security logs).

EWS.AccessAsUser.All (EWS Backend Only) - Legacy Permission

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

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 an email in Outlook and enters the distribution list in the To field
  2. ContactMonkey Add-in captures the list email address
  3. Using GroupMember.Read.All, ContactMonkey searches within your existing groups using an ID
  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)

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 or P2)
  • 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.

Related articles