HaloCRM

HaloCRM Guides

Guides > Google Mail Setup (Setting up Google Application)

Google Mail Setup (Setting up Google Application)

In this guide we will cover:

- Pre-Requisites

- Create a Mailbox in Halo

- Setting up a Google Mail App

- Pug Credentials into Halo

- Additional Setup


In this guide we will cover how to plug Google mailboxes in Halo, including how to set these up to allow the ingestion of emails into a mailbox of this type to create tickets in Halo. If you are looking to connect a mailbox of a different type ensure you use the guide dedicated to that mailbox type, such as:


Pre-Requisites

1. The incoming service must be enabled in your instance. This is activated for all hosted customers automatically. 


If you are On-Prem and 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 both the "Use Incoming Service" checkbox and that the "Use Scheduling Service" checkbox is set to yes.


2. The mailboxes you are connecting will need a dedicated (Google) licence (unlike M365). This is required in order for your mailbox to be accessed via the API, which is needed as Halo uses the Gmail API to access and process mail within the mailbox.  For more information on licencing in Google check out Google's documentation: Assign, remove, and reassign licenses.


If you are an On-Prem (self-hosted) customer please see Creating a Mailbox Overview for the pre-requisites you will require for connecting a mailbox to Halo. 


Create a Mailbox in Halo

To begin setup you will need to create a new mailbox in Halo with the mailbox connection type "Google". To do this, go to Configuration > Email > Mailbox Setup > New and give the connection a name.


Select the Google mailbox type and save. 


Once saved, you will be able to add credentials under the "Credentials" button. 

Fig 1. New Google Mailbox in Halo


When adding credentials you will need to enter a client id and secret. 

Fig 2. New Mailbox credentials


The next section will walk through how to create a project in Google to obtain these credentials. 


Note: You will notice it is possible to configure multiple sets of credentials here, this is to allow you to configure credentials for another mailbox (of the same type) to be used in a different (UAT/Dev) instance. So a single Halo mailbox can contain credentials to access multiple Azure mailboxes. Each of these mailboxes will be linked to your production, UAT or dev instance, each instance will then only process the mail in the mailbox the associated credentials give access to. For more information checkout Creating a Mailbox Overview.


Setting up a Google Mail App

Login to https://console.cloud.google.com.


Create a new Project

Select New Project from the Select a Project menu or Create Project from the Dashboard.

Fig 3. Creating a new project


Give the project a name and create it.

Fig 4. Name and Create Project


Enable GMail API for the Project

Now within the project head to API and Services, (you can search for this page if you cannot find it in your navigation).

Fig 5. APIs and Services Area


Select Enable APIS and Services.

Fig 6. Enabling APIs


Search for "Gmail API" and enable this API for use.

Fig 7. Enabling the API


Once enabled head to the "OAuth consent screen" section within the APIs and services area. 

Fig 8. OAuth consent screen


If this is a new project you will need to configure your Google Auth platform for this project. Do this by clicking "Get started" once in the Auth Platform area. 

Fig 9. Start configuring Google Auth Platform


When setting up give the app a name and choose a support email. The support email will be displayed when authenticating the connection between Halo and Google. Set the audience to be "Internal". Then add contact information and finish. 

Fig 10. Configuring Auth Platform


Add Scopes to Project

Now you will need to add the following scope to the project:

  • https://mail.google.com/

Add this under the "Data access" tab.

Fig 11. Add scope


You can search for the scope here, select it and click "Update".

Fig 12. Select and add scope


Remember to save once added.

Fig 13. Save scopes


Now you can generate a client ID and secret for the project. These will be plugged into Halo to authenticate the connection. 


Generate Client ID and Secret

In the project, head to the "Clients" tab and "Create client", ensure you create an OAuth 2.0 client.

Fig 14. Create Client credentials


Set the application type to be "Web application" and add a redirect URI. The redirect URI will follow the format:

The exact redirect URI needed can be found on the new credentials screen for the mailbox in Halo, as shown in Figure 2.  


Fig 15. Example Client setup


Once created you will be provided your client id and secret, copy these. 


Note: The whole client ID and secret will need to be used, including the '.apps.googleusercontent.com' section.

Fig 16. Client ID and secret


Now you can head back to Halo and plug these credentials into your mailbox. 


Plug Credentials into Halo

Paste the client ID and secret into the mailbox credentials in Halo. When saved you will be given an option to "Sign into Google". Sign in using the dedicated Google Workspace user account for the mailbox. 


Important: The mailbox account you sign into here should not be your personal email.

Fig 17. Sign in with Google to authenticate the connection


Once completed you should be redirected back to the mailbox setup screen. If the authorisation was successful the Sign In button will have changed to a disconnect button.


Remember to save once completed.


Additional Setup

There are various additional settings for the mailbox, that control how incoming/outgoing emails are processed. For a breakdown of what each of these settings do check out Mailbox Setup.


Once the mailbox is setup you may want to set this as the (global) default mailbox used for outgoing mail. 


To do this head to configuration > email > general settings > outgoing email defaults. Here use the dropdown to select the mailbox you would like to be used as default. 

Fig 18. Set outgoing email default


You can override the mailbox that is used in various scenarios. Overrides can be set for various entities. For details on where overrides can be set checkout Mailbox Overrides. 


Setting up Deletion Labels

Within the mailbox incoming config, you have the option to Assign emails to the following label when they are deleted.


If you are using a system label, you can enter the name of the label in full caps. If you are using a user defined custom label, you need to provide it's ID in the following format:

  • Label_5915939116930758527


You can find the label ID by making a change to the label within Gmail, such as by toggling the show/hide and inspecting the network call it makes. You will just need to remove the '^x_' from the beginning and replace it with 'Label_', as demonstrated above.



Fig 19. Detailing how to obtain a user define label's ID

Popular Guides

Pin It on Pinterest