Purpose

The purpose of this article is to provide information to Outreach Users and Admins about the Microsoft Graph Integration. The Graph Integration is a new method for connecting Microsoft/Office 365 mailboxes to Outreach. The Microsoft Graph is a modern API, supported by Microsoft, that allows users to give access to their mailboxes in a more modern and compliant way.

Intended Audience

• Outreach Users
• Outreach Admins

About Microsoft Graph Integration

Microsoft Graph Integration is a new method that enables organizations to access various data in Microsoft Cloud. Microsoft Graph is a more modern substitute for EWS (Exchange Web Services) API and therefore a more compliant way to connect Microsoft 365 data to Outreach. Outreach supports Microsoft Graph Integration for connecting user calendars and user mailboxes, which previously was possible over EWS API only.

The Microsoft Graph Integration enhances security when used with OAuth 2.0. Additionally, customers who use multiple email aliases and UPN names can connect mailboxes to Outreach in a seamless way using Microsoft Graph API.

OAuth scopes overview

Outreach requests the following list of permissions which need to be granted by a user during OAuth flow in order to be able to connect their Microsoft / Office 365 mailbox and calendar to Outreach via Microsoft Graph:

User.Read - to get the basic user info that’s required to access and connect to user mailbox to Outreach

Calendars. ReadWrite - to sync user calendar and schedule new events in it

MailboxSettings.Read - to get user signature and timezone

Mail.ReadWrite - to sync emails, create draft emails

Mail.Send - to send emails on behalf of user

Offline_access - to enable applications to work in the background, without the user physically using Outreach. For example, Outreach can schedule automated emails while the user is not logged into Outreach.

Mail.ReadWrite, Mail.Send and Offline_access - new scopes added to the Microsoft Graph Integration for email, which is necessary for making Microsoft / Office 365 mailboxes fully operational in Outreach.

Notes

• Ensure your Office 365 or Azure admin approves users for the Outreach application (if required by the Azure tenant configuration) in Azure Admin Center or by starting the admin consent flow from Outreach Admin Consent before letting users connect their mailboxes over to Graph. 
• If not, users will see a Need admin approval page and will not be able to proceed. 
• This may impact their calendar connectivity as well; it will stop their calendar from being synced to Outreach until the admin approves new scopes.

Process

In order to start using Graph API, follow the steps below, depending on your current setup.

Note

• We recommend migrating to Microsoft Graph before or after work hours.
• We recommend starting the migration with several users first and proceeding with the rest of the organization after confirming that important workflows work as expected for the initial group.
• Only end users can confirm and finish the Microsoft Graph configuration, as the end user’s credentials must be provided during the OAuth authentication step.
• If end users require Outlook add-in from Outreach in their day-to-day workflow, no actions are needed from them - both legacy and new add-in versions are compatible with the Graph API.
• Recommendation
  • For users who are using Outlook add-in on a daily basis, we recommend installing the new add-in.
  • For users who are not frequent users of the Outlook add-in, we recommend installing the legacy add-in.
• Read more about the differences between the legacy and new add-in.
• Microsoft provides the ability for organizations to grant tenant-wide admin consent to an application like Outreach.
  
  • This allows admins to consent on behalf of all users of an org, so users do not need to consent or grant permissions for Outreach individually. This removes the consent step from non-admin users. Refer to Office 365 documentation for process details.
• For existing users, there can be some impact to the calendar configuration workflow when users connect via Microsoft Graph for email.
  • Users can expect a slightly different calendar workflow due to Outreach connecting to the calendar via Microsoft Graph vs EWS API.

New or existing user with one mailbox

If you are a new user who is connecting their mailbox to Outreach for the first time, or you are an existing user with one mailbox, follow the steps below.

1. Navigate to Settings > You > Mailboxes.
2. Click Edit or Set up account on the default mailbox.
3. Select Office 365 OAuth (recommended) in the Email Provider drop-down list.
   
4. Click Connect with Office 365. This will start the Microsoft/Office 365 OAuth flow.
   
5. Depending on your organization’s settings, you will be asked to provide user consent in order to authorize Outreach to access your data. Click Accept.
6. Depending on your organization’s settings, you will be asked to provide admin consent in order to authorize Outreach to access your data. Click Request approval. More information about this process can be found here.
   
7. When the OAuth flow is finished successfully, the mailbox will show Connected.
8. Enable Syncing and Sending functionality using the corresponding toggles.
9. Save mailbox settings.

Your mailbox is ready now for syncing and sending emails using Outreach.

Existing Outreach User with Several Email Aliases / Mailboxes

Some existing Outreach users may have several email aliases/ mailboxes configured in Outreach. This could be because your Office 365 account also has several aliases, or because you use Outlook add-in from Outreach, which requires a special setup.

If you are one of these customers, please follow the steps below in order to migrate your mailbox connection to Graph API.

1. Navigate to Settings > You > Mailboxes.

You will see the following screen with several mailboxes, where one mailbox has send/sync enabled; this is your primary alias configured in your Office 365 account. You will also see one or more mailboxes with send/sync not enabled; these are your secondary aliases / mailboxes that you use for sending and receiving emails.

For example, on the screenshot below john@acme.com is a primary alias/mailbox and john.work@acme.com is a secondary alias/mailbox.

1. Identify the mailbox that you are using with Outreach (if you are not sure, please reach out to your admin).
2. Click Edit or Set up account.
3. Select Office 365 OAuth (recommended) in the Email Provider drop-down list.
4. Click Connect with Office 365.
5. Depending on your organization’s settings, you will be asked to provide user consent in order to authorize Outreach to access your data. Click Accept.
6. Depending on your organization’s settings, you will be asked to provide admin in order to authorize Outreach to access your data. Click Request approval to do so. More information about this process can be found here.
7. When the OAuth flow is finished successfully, the mailbox will show Connected.
   
8. Enable Syncing and Sending functionality using corresponding toggles for this mailbox. Keep sync/send disabled for other mailboxes.
9. Save mailbox settings.

Your mailbox is ready now for syncing and sending emails using Outreach.

Migrate Your Secondary Mailbox to Graph API

1. Identity the mailbox that you are using with Outreach. If you are not sure, please reach out to your admin.
2. If it’s one of the secondary mailboxes, disable Sync for the primary mailbox. Keep Send enabled in order scheduled emails can still be sent.
3. Click Edit or Set up account for the secondary mailbox.
4. Select Office 365 OAuth (recommended) menu item in the Email Provider drop-down list.
5. Click Connect with Office365.
6. Depending on your organization’s settings, you will be asked to provide user consent in order to authorize Outreach to access your data. Click Accept.
7. Depending on your organization’s settings, you will be asked to provide admin consent in order to authorize Outreach to access your data. Click Request approval to do so. More information about this process can be found here.
8. When the OAuth flow is finished successfully, the mailbox will show Connected.
9. Enable Syncing and Sending functionality using corresponding toggles for this mailbox. Keep sync/send disabled for other mailboxes.
   
10. Save mailbox settings.
11. Disable Send for the primary mailbox.
12. Make the secondary mailbox the default mailbox.

The final step is to reassign any scheduled emails which are yet to be sent from the primary to the secondary mailbox that you just moved to Graph API. To do so, follow the steps below.

1. Go to Settings and click Sequences States under the System Activity section.
2. Select all the emails you want to transfer. Click the Settings and select Assign Mailbox.
3. Select the following fields:
   • From: the secondary mailbox that was moved to Graph API
   • Update existing undelivered emails?: Yes, update the mailbox of any existing undelivered emails.
     
4. Click Assign.

Your mailbox is ready now for syncing and sending emails using Outreach.