Microsoft 365 Outlook

This article describes how to set up a Microsoft 365 Outlook integration for the Email Listener. To learn more about the Email Listener, see Email Listener.

Before you begin…

You need to have a Microsoft 365 subscription. For development purposes, you can take advantage of the Microsoft 365 Developer Program. It provides a free 90-day subscription pre-provisioned with all Office 365 apps.

1. Find your User Principal Name.

Microsoft uses Azure Active Directory (Azure AD) for all its online business services (e.g., Microsoft 365, Power Apps, Azure, etc.). In Azure AD, all users have a sign-in name, which is the name they use when they log in to their accounts. This name is called the User Principal Name (UPN) and uniquely identifies a user in the Directory.

The User Principal Name is formatted as an email address (e.g., [email protected]), but it is not always the same as the user’s actual email address. By default, when an administrator creates a new user in Microsoft 365, they specify the User Principal Name, which also sets the default email address, but this value can be changed later.

When configuring a Microsoft 365 Outlook setup in the Email Listener, you need the User Principal Name. To find it, log in to the Azure portal, click Azure Active Directory, and then click Users in the left-hand panel.

2. Register an application.

To use our Microsoft 365 integration, you need to register an application with the Microsoft identity platform. Registering your application establishes a trust relationship between your app and the Microsoft identity platform. 

To register your application:

1. Sign in to the Azure portal.

2. Search for and select Azure Active Directory.

3. Under Manage in the left-hand panel, go to App registrations > New registration.

4. Enter a Name for your application.

5. Under Supported account types, select Accounts in this organizational directory only.

6. Do not enter anything in Redirect URI (optional).

7. Click Register to complete the initial app registration.

Your registration page should look similar to the example below.

3. Find the Application (client) ID and Directory (tenant) ID.

When registration finishes, the Azure portal displays the app registration's Overview pane. You can go to the Overview pane from the left-hand sidebar at any time. 

In the Overview pane, you can see the values for Application (client) ID and Directory (tenant) ID. Record both of these values, as you will need them when setting up the Email Listener. 

Your Overview pane should look similar to the example below:

4. Add credentials.

By adding credentials to the registered application, you allow the application to authenticate as itself, requiring no interaction from a user at runtime.

To add credentials:

1. In App registrations, click on the name of your application.

2. Under Manage in the left-hand sidebar, go to Certificates & secrets > Client secrets > New client secret.

3. Enter a description for your client secret.

4. Select an expiration for the secret, or specify a custom lifetime.

   • Client secret lifetime is limited to two years (24 months) or less. You cannot specify a custom lifetime longer than 24 months.

   • Microsoft recommends that you set an expiration value of less than 12 months.

   • Click Add.

IMPORTANT: Record the secret's value (as opposed to Secret ID), which you will enter when configuring the Email Listener block. This secret value will not be visible again after you leave the page.

5. Add permissions.

The Email Listener needs to read, fetch, move, and delete emails in an email account. Therefore, the registered application should have proper permissions in Azure Active Directory. 

To add the required permissions to your application, follow these steps:

1. In App registrations, click on the name of your application.

2. Under Manage in the left-hand sidebar, go to API permissions > Add a permission.

3. In the opened window under the Microsoft APIs tab, click Microsoft Graph.

4. In the next window, click Application permissions.

5. In the opened list, under Mail, select Mail.ReadWrite. Under User, select User.Read.All. 

6. Click Add permissions.

Initially, the status of these permissions is “Not granted.”

6. Have an admin grant the permissions.

After proper API permissions have been requested, an admin should grant those permissions to the registered application. 

An admin can follow these steps to grant permissions:

1. In App registrations, click on the name of your application.

2. Under Manage in the left-hand sidebar, go to API permissions > Grant admin consent for tenant_name.

3. In the Grant admin consent confirmation dialog that appears, click Yes.

Important security considerations

By default, granting the above permissions to the registered application gives it access to all mailboxes in an organization on Exchange Online. There are scenarios where administrators may want to limit an app’s access (and, in turn, the Hyperscience Email Listener) to only specific mailboxes instead of all Exchange Online mailboxes in the organization. To do so, follow the steps in Microsoft’s Limiting application permissions to specific Exchange Online mailboxes. 

One of the steps in this process is creating a new mail-enabled security group or using an existing one if it already exists. To create a mail-enabled security group, follow the steps in Microsoft’s Manage mail-enabled security groups in Exchange Online.