Gmail Integration Setup Guide

Gmail Integration Setup Guide

Overview

This guide explains how to configure Gmail as the email provider in Horizon. Once configured, Horizon will use the connected Gmail account to send and receive emails related to trip communications, notifications, and other system messages.

Important: Account Requirements

You must use a shared mailbox or service account for this integration, not a personal Gmail account.

The connected Google account will be used to: - Send all outbound emails from Horizon - Read and track email conversations related to trips - Store sent messages with an “FMSApp” label for organization

Using a shared mailbox (e.g., operations@yourcompany.com) ensures: - Business continuity if personnel changes occur - Appropriate access controls for multiple team members - Clear separation between personal and business communications

Prerequisites

Before starting, ensure you have:

  1. A Google Workspace or Gmail account designated as your shared mailbox 
  2. Access to Google Cloud Console (console.cloud.google.com) 
  3. Administrator access to Horizon configuration pages

Part 1: Google Cloud Console Setup

Step 1: Create or Select a Google Cloud Project

1. Navigate to Google Cloud Console

2. Sign in with your organization’s Google account

3. Click the project dropdown in the top navigation bar

4. Either select an existing project or click New Project

5. If creating a new project:

– Enter a project name (e.g., “Horizon Email Integration”)

–  Select your organization if applicable

–  Click Create

Step 2: Enable the Gmail API

1.  In the Google Cloud Console, go to APIs & Services > Library

2.  Search for “Gmail API”

3.  Click on Gmail API in the results

4. Click Enable

Step 3: Configure the OAuth Consent Screen

1. Go to APIs & Services > OAuth consent screen

2.  Select the user type:

–   Internal: If all users are within your Google Workspace organization (recommended)

–  External: If the app needs to be accessible outside your organization

3.    Click Create

4.    Fill in the required fields:

–  App name: Enter your application name (e.g., “Horizon”)

–  User support email: Select an appropriate email address

–  Developer contact information: Enter your email address

5.   Click Save and Continue

6.    On the Scopes page, click Add or Remove Scopes

7.  Find and select https://mail.google.com/ (full Gmail access)

8.   Click Update, then Save and Continue

9.  Complete the remaining steps and click Back to Dashboard

Step 4: Create OAuth 2.0 Credentials

1. Go to APIs & Services > Credentials

2.  Click Create Credentials > OAuth client ID

3.   Select Web application as the application type

4. Enter a name (e.g., “Horizon OAuth Client”)

5. Under Authorized redirect URIs, click Add URI

6.  Enter your redirect URI in the following format:

    

             
Replace https://horizon.portside.co/ with your actual Horizon URL (in case of multi tenant).

7.  Click Create

8.  A dialog will display your Client ID and Client Secret

9.  Copy both values and store them securely. You will need these in the next section.

Part 2: Horizon Configuration

Step 1: Access Gmail Configuration

1.  Log in to Horizon with an administrator account

2.   Navigate to System Configuration > Gmail Configuration

Step 2: Enter OAuth Credentials

1.     In the Client ID field, paste the Client ID from Google Cloud Console

2.      In the Client Secret field, paste the Client Secret from Google Cloud Console

3.      Click Save Gmail Configuration

Step 3: Authorize the Gmail Account

1.   Click Authorize Gmail

2.   You will be redirected to Google’s sign-in page

3.    Sign in with the shared mailbox account you want to use for sending emails

4.    Review the permissions requested and click Allow

5.    You will be redirected back to Horizon

6.     A success message will confirm the authorization

7.    The Sender Email Address will be automatically populated with the authorized account’s email

Step 4: Test the Connection

1.   Click Test Connection

2.     A successful test will confirm:

–   Connection to Gmail is working

–    Required permissions are granted

–     The FMSApp label has been created in Gmail

Verification

After completing the setup, verify the following:

1.   The Gmail Configuration page shows a green “Gmail account authorized” message

2.   The authorized date is displayed

3.  The sender email address matches your shared mailbox

4.   The Test Connection button returns a success message

You can also verify in Gmail: 1. Sign in to the shared mailbox account at gmail.com 2. Check the left sidebar for an “FMSApp” label 3. This label will be used to organize emails sent through Horizon

Managing the Connection

Disconnecting Gmail

To disconnect the Gmail integration:

1.  Navigate to System Configuration > Gmail Configuration

2.   Click Disconnect

3.   The authorization tokens will be removed

4.   You can re-authorize at any time by following the authorization steps again

Re-authorization

Re-authorization may be required if: - The refresh token expires (rare, but possible after extended periods of inactivity) - You revoke access from Google Account settings - The OAuth credentials are regenerated in Google Cloud Console

To re-authorize, click Authorize Gmail and complete the sign-in process again.

Troubleshooting

Issue

Possible Cause

Solution

“Invalid authorization request”

Redirect URI mismatch

Verify the redirect URI in Google Cloud Console matches your Horizon URL exactly

“OAuth authorization denied”

User declined permissions

Click Authorize Gmail again and accept all requested permissions

“Gmail configuration not found”

Configuration not saved

Save the Gmail Configuration before clicking Authorize

“Permission denied” error

Insufficient API scopes

Ensure the Gmail API scope is added in OAuth consent screen

Test Connection fails

Token expired or revoked

Click Disconnect, then re-authorize the Gmail account

Emails not sending

Account not fully authorized

Verify authorization status shows green and test connection succeeds

Common Configuration Errors

Redirect URI Mismatch

The redirect URI must match exactly, including: - Protocol (https:// vs http://) - Domain name - Path (/gmail-callback) - No trailing slash

API Not Enabled

If you receive API-related errors, verify that the Gmail API is enabled in your Google Cloud project under APIs & Services > Enabled APIs & Services.

Security Considerations

•    Store OAuth credentials securely; do not share them publicly

•    Use a dedicated shared mailbox rather than a personal account

•    Regularly review authorized applications in Google Account settings

•    Consider restricting OAuth consent to internal users if using Google Workspace

•    The integration requests full Gmail access to support both sending and reading email conversations

Support

If you encounter issues not covered in this guide, contact your system administrator or Portside support with: - The exact error message displayed - The step at which the error occurred - Your Horizon URL (without credentials)


    • Related Articles

    • FlightBridge Integration

      FlightBridge is an integrated service that lets users easily order catering, ground transportation, hotels, and airline travel. It also provides FBOs with arrival times and service requests. Learn more at FlightBridge.com. ? Setup & Configuration To ...

    • Basic Feature Guide for Horizon

      This guide provides a detailed walkthrough of the new software designed to streamline the management of your private aircraft crew and fleet. We'll cover personnel data, crew qualifications, scheduling, aircraft maintenance, and more, all within a ...

    • Crew Management Guide

      ?‍✈️ Crew Management Guide This guide provides a comprehensive overview of managing flight personnel within the Horizon platform, from crew profiles and qualifications to legality, scheduling, and trip assignments. ? Accessing the Crew Section The ...

    • Quick Guide: Basic Configuration for Charter Fee and Expense Types

      This guide outlines the initial steps to set up the foundation for fees and expenses within the Charter system. You first define the types of fees and expenses you will use. Then, you configure the specific fees and expenses under those types, ...

    • Quick Guide: Creating a Trip from the Aircraft Schedule

      This guide outlines the steps to create a new trip directly from the Aircraft Schedule. 1. Initiate New Trip: Left-click on the column representing the day you wish to schedule the trip. Locate the "New Trip" section. (Note: If the "New Trip" section ...