Utility Account Set Up

EWS Restrictions

Out of the box, ContactMonkey uses EWS (client side) to count the total number of recipients within the Distribution lists, dynamic lists and Office 365 groups that are placed in the “To” field during a campaign send. We use this recipient count as part of the analytics to help your Internal Comms team to help track their engagement.

However, using EWS through the Office 365 web add-in has several restrictions, one of which is that the API has a 1mb limit on the response. In order to bypass the above limitation, you will need to set up a utility account.

If your count for certain distribution lists shows up as 1 recipient, your team will need to set up Graph Utility Count.

Consent to Application

In order to bypass this limitation, your team will need to create a utility account that has
access to make the required Microsoft Graph calls. Once an account has been created, your
account manager can enable the feature. This will allow your Org Owner/Admin to
“Connect” the utility account using OAuth2 via their settings page. Once the Utility account
has been connected, ContactMonkey will use this account when users within the
Organization send Overall campaigns.

Your IT administrator will need to provide consent to the application. This can be granted
on behalf of your Organization via this URL.

Permissions that require Admin Consent

● Read directory data - This is referring to the Directory.Read.All scope.
● Read all users' full profiles - This is referring to the User.Read.All scope

The combination of these two permissions allows ContactMonkey to obtain a list of all your tenant’s
lists such as Distribution Lists and Office 365 Groups, on behalf of the signed-in user. When Internal
Comms personnel use ContactMonkey to send a campaign to specific lists, ContactMonkey obtains
the inputted DLs using our Web Add-in. We pass these along and use the email addresses to search
through all the lists so that we can obtain the ID of each DL. We then use the IDs to expand all the
recipients inside the selected lists so we can obtain the email address for each individual recipient in
the list. We use the email address to count the unique number of recipients in the list, including any
recipients in nested lists. Every nested list is expanded until each recipient email address can be
obtained.

Permissions that require User Consent

(Consent for the below has already been granted for a separate ContactMonkey Application)
Access your data anytime: This is referring to the offline_access scope. Obtaining a list of your
tenant’s DLs and then expanding each list (including nested ones) takes a long time so we perform
these tasks in a background job. In order to perform these tasks, we require offline access to
process things behind the scenes. Note that the data we get access to offline is only what has been
approved as part of the other scopes. It's just the data we were given access to as part of the set of
scopes we requested. Requiring offline_access is a pretty common need for SaaS platforms that
perform tasks on behalf of the user.

openid, email and User.Read

These permissions are standard permissions required to connect your account to our service using
OAuth 2. We rely on the email address and profile information obtained during the connecting
process to store which account was used so that it can be displayed as information to the Internal
Comms personnel in our SaaS.

Supported List Types

Users within the organization can also “Test” the count in advance of sending, to ensure their lists are supported. Please refer to the table below for supported list types: