HaloCRM Guides

Guides > Azure Mail Integration (Webhook Method Included)

Azure Mail Integration (Webhook Method Included)

This video covers the Mailbox Setup for Email Processing via Webhooks (Read the guide for full setup and how to configure error notifications per agent)

Supported mailboxes

Halo can connect to standard licensed mailboxes and also shared mailboxes. All other kinds of mailboxes are currently unsupported.

Enabling the Incoming Service/ Scheduling Service

The contents of this guide are based on the incoming service being enabled in your Halo instance. If the service is not yet active in your instance, and you are unsure of the implications of activating it, please contact your account manager or the Halo support team.

To check whether the service is currently enabled, navigate to Configuration > Advanced Settings > Backend Services, check that the incoming service checkbox is on and that the scheduling service is set to yes. On-Premise customers will have the scheduling handled via the Halo DB Integrator, this refreshes the subscription of the mailbox for On-Premise customers(the DB integrator is used to queue the scheduling service for everyone. If you're hosted, the scheduling service will process incoming emails, including the refreshing of tokens/subscriptions. By default DB integrators are handled by Halo for all hosted customers). If not all prerequisites have been met, then you will be unable to activate the service for the time being, NHServer must be on version 1364 or higher. Please contact the Halo support team for assistance if you are unsure how to meet the prerequisites.

For On-Premise Customers

The frequency in which the scheduled task should be run is determined by the integrations that are being processed by the Halo DB Integrator, and how much data will be processed via the third-party sync. The incoming mail should be enabled on the list of integrations within the Halo DB Integrator. An integration such as incoming mail is recommended to run every few minutes, whereas the Azure Active Directory integration that may import thousands of users must be run much less frequently, otherwise, the sync will never be able to complete.

At this point it is worth going to configuration > email and enabling these settings:

As these not being enabled could prevent certain notifications and emails getting send in either of these methods.

Choosing an incoming method

Once the incoming service is enabled, navigate to Configuration > Email > Mailbox Setup to add a new/edit an existing mailbox. Choose a name and select Office 365/Azure as the connection type.

Select the Authentication Method: "Client Credentials" to use the Webhook method on the mailbox.

Underneath the basic configuration options, you will find a section for Office 365/Azure. At the top of this section, there is an option to choose the method used for processing emails. The two options are a mailbox scan or webhooks.

Depending on the option you choose, different configuration is required in both Halo and Azure. By changing the drop-down, you will notice that a different set of configuration options/instructions are displayed on the screen. A brief explanation of what each method does and how it differs is as follows:

Mailbox Scan

The task scheduling service (which is automatically enabled when the incoming service is enabled) scans the mailbox every 3-5 minutes. This method uses delegate permissions in Azure and requires additional permissions for a shared mailbox.

Webhooks

A webhook is sent to the Halo API when an email is received in the mailbox, providing instant delivery and processing of any emails that are received. The task scheduling service that is also used for the mailbox scan will also run to retry any potential failed webhooks, but the frequency will be decreased. This method uses application permissions in Azure and has fewer required permissions than the above method. There are additional security steps that are recommended when using this method, which are outlined in more detail later on.

Configuring an Azure Application

Once you have selected the method you would like to use for processing emails, you must configure an application in Azure before continuing with any further Halo configuration. Both setup steps for both methods are outlined in this section.

Start by navigating to the Azure portal and select New Registration in the App Registrations. There are three required fields on the creation screen:

Name - give your application a sensible name so it can be easily referred to later.
Supported account types - must be single-tenant. Multi-tenant is not supported and will cause issues later.
Redirect URI - only required if you are using Mailbox Scan as the method. The platform should be "Web" and the URL should be your Halo application URL followed by /azure/auth. For example, https://myapp.haloitsm.com/azure/auth.

Once registered, take note of the Application (client) ID on the overview tab, as well as the Directory (tenant) ID. These values will be needed later.

Next switch to the Certificates and Secrets tab. Generate a new secret with a sensible expiry date. Make a note of the value generated and the expiry date.

The final step is to add the relevant permissions to the Azure app. As previously mentioned, the required permissions depend on the method that you have selected. The permissions listed below can also be seen within the Halo mailbox setup screen.

Mailbox Scan permissions:

All of the following permissions must be of type delegate.

Mail.ReadWrite
Mail.Send
Mail.ReadWrite.Shared(only required if using a shared mailbox)
Mail.Send.Shared(only required if using a shared mailbox)

Webhook permissions:

All of the following permissions must be of type application.

Mail.ReadWrite
Mail.Send

Both applications require the offline_access permission, which is a delegated permission.

Each permission can be added by following these steps:

1. Navigate to the API permissions tab and select Add a permission.

2. Select Microsoft Graph as the API.

3. Choose the type of permission depending on the method you are using. Choosing an incorrect permission type will prevent you from fully configuring the mailbox later in Halo.

4. Search for the permissions, and select the necessary permissions that are required.

5. Once added, grant admin consent for the tenant:

Additional restrictions (Webhooks only)

If you are using the webhooks method, it is highly recommended that you create an application access policy to restrict which users your Azure application can access. Without this, the application will be able to read, write and send emails for all users within the Azure tenant.

To find out more about how to add an application access policy, follow this guide: https://learn.microsoft.com/en-us/graph/auth-limit-mailbox-access#configure-applicationaccesspolicy.

Connecting to the mailbox

Once you have successfully created your Azure app, you can now add the details to the mailbox configuration in Halo and complete the rest of the setup.

The following four fields must be completed and the mailbox must be saved before continuing, regardless of the chosen method. The Microsoft Graph Global Service should always be chosen as the authority unless you know that your Azure tenant uses a different authority.

If you are using the Mailbox Scan method, then an option to configure a shared mailbox is also available.

If you are using webhooks, then an email address field is available. This field can accept standard or shared mailboxes. The only additional requirement is that the owner of the email address must have a UPN value that matches the email address.

Once saved, the following should be completed for each method type.

Mailbox Scan

If using the mailbox scan method, click the authorize application button to initiate a sign-in flow with Azure. Be aware that the user who completes the sign-in flow will have the emails from their inbox processed. A warning will alert you to this before proceeding.

Once you are connected, the connected email address will be shown on the setup screen. All values will be locked in and can only be altered by using the disconnect button first.

Webhooks

If using the webhooks method, you are not required to complete a sign-in. Instead, a subscription will be created for the chosen email address. Click the Create Subscription button to register the subscription. If successful, the details of the subscription will be displayed, including the subscription's expiry date. The subscription can be cancelled at any time using the Cancel Subscription button.

The subscription expiry is always set to the maximum allowed value in Azure. It is automatically renewed whenever the expiry date is within 2 days of expiry, either during the processing of a webhook or by the task scheduler if no webhooks have been received to trigger the refresh.

From the moment the subscription has been created, webhooks will be sent to Halo from Azure to process any new emails received in the user's mailbox.

After connecting the webhook mailbox, if you are deleting your old mailbox that was connected to the outgoing default, make sure to go to the "Outgoing Email Defaults" found in configuration > email, and change the default connection to the new mailbox, without doing this step, you will not see anything populate in the email from field when emailing clients.

Manual imports

At the bottom of the incoming tab, it is now possible to import emails manually.

After configuring a mailbox that is using the Mailbox Scan method, it is recommended that you attempt to click the Import Emails button. This will highlight any potential permissions issues (especially if using a shared mailbox) so that they can be rectified before signing off on your mailbox configuration.

Logging

As part of the new incoming service, it is now possible to see the log for every email that has been processed via the service. This can be found on the Inbound Log tab of the mailbox, or in Configuration > Advanced > Backend Services > Backend Service Monitoring.

Both screens allow you to see some basic information about the incoming email, and whether it was successfully processed.

By clicking on the record, more elaborate details about the email can be found, including the details of each processing attempt. This is located on the Requests tab. Each request can be opened, where the raw data for the request can be observed, as well as a detailed processing log for help understanding how an email has been processed.

Error Notifications

Send Error Notifications for emails and the Halo Integrator, to specific agents (Configuration > Teams & Agents > Agents > Click into an Agent > *Preferences Tab*):