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.
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.
- 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, please make sure it is upgraded to its latest version prior to moving the user mailbox to Graph API. Users not on the latest version may encounter errors.
- 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.
- Navigate to Settings > You > Mailboxes.
- Click Edit or Set up account on the default mailbox.
- Select Office 365 OAuth (recommended) in the Email Provider drop-down list.
- Click Connect with Office 365. This will start the Microsoft/Office 365 OAuth flow.
- 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.
- 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.
- When the OAuth flow is finished successfully, the mailbox will show Connected.
- Enable Syncing and Sending functionality using the corresponding toggles.
- 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.
- 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.
- Identify the mailbox that you are using with Outreach (if you are not sure, please reach out to your admin).
- Click Edit or Set up account.
- Select Office 365 OAuth (recommended) in the Email Provider drop-down list.
- Click Connect with Office 365.
- 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.
- 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.
- When the OAuth flow is finished successfully, the mailbox will show Connected.
- Enable Syncing and Sending functionality using corresponding toggles for this mailbox. Keep sync/send disabled for other mailboxes.
- Save mailbox settings.
Your mailbox is ready now for syncing and sending emails using Outreach.
Migrate Your Secondary Mailbox to Graph API
- Identity the mailbox that you are using with Outreach. If you are not sure, please reach out to your admin.
- 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.
- Click Edit or Set up account for the secondary mailbox.
- Select Office 365 OAuth (recommended) menu item in the Email Provider drop-down list.
- Click Connect with Office365.
- 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.
- 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.
- When the OAuth flow is finished successfully, the mailbox will show Connected.
- Enable Syncing and Sending functionality using corresponding toggles for this mailbox. Keep sync/send disabled for other mailboxes.
- Save mailbox settings.
- Disable Send for the primary mailbox.
- 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.
- Go to Settings and click Sequences States under the System Activity section.
- Select all the emails you want to transfer. Click the Settings and select Assign Mailbox.
- 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.
- Click Assign.
Your mailbox is ready now for syncing and sending emails using Outreach.