Skip to main content

Google Email (Gmail) Integration

The Google Email integration connects Harmony to Gmail so that Companion and Harmony's automations can read messages, draft replies, and send email on your behalf when you approve it. Like the rest of Google's APIs, Gmail uses OAuth 2.0 for authorization — which means you (the workspace admin) register a Google Cloud OAuth application, enable the Gmail API on it, and paste the resulting Client ID and Client Secret back into the Harmony setup form.

Once configured at the workspace level, anyone in your organization who connects Gmail will go through your own Google Cloud OAuth app — you don't have to share credentials, and each user still controls their own mailbox connection.

Configuring the Google Email integration at the workspace level requires the integrations:write:all permission. See Roles and permissions. Once the workspace credentials are saved, individual users can connect their own Gmail account from Marketplace → Apps → Google Email.

Step 1. Open the Marketplace​

In Harmony, open the Marketplace tab from the sidebar and select the Google Email integration tile.

Step 2. Click "Set up"​

After clicking Set up, Harmony shows a setup form. This form contains everything you need to wire your Google Cloud OAuth application to Harmony, including:

  1. The Redirect URI to register in Google Cloud.
  2. The list of required OAuth scopes.
  3. A field for the Client ID.
  4. A field for the Client Secret.

You will copy values from this form into your Google Cloud setup, then copy the generated Client ID and Client Secret back into this same form. Google uses OAuth 2.0 for this authorization flow.

Step 3. Open Google Cloud Console and prepare a project​

Sign in to the Google Cloud Console and create a new project (or select an existing one) to host this integration. Google recommends using a dedicated project for OAuth-based access to Google APIs so that scopes, credentials, and audit history stay isolated from other workloads.

If you have already created a Google Cloud project for the Google Meet integration, you can reuse it here — just enable the Gmail API on the same project in the next step. Each integration still needs its own OAuth client (Client ID + Client Secret), since each one uses a different redirect URI.

Step 4. Enable the required API​

Inside the project, enable the API that the Google Email integration needs. Google OAuth integrations require the relevant API access to be enabled before authorization can complete successfully.

Enable the following API:

  • Gmail API

Step 5. Set up the Google Auth Platform​

Once the API is enabled, configure the Google Auth Platform / OAuth consent screen. This is the screen users see when Google asks them to authorize the application.

5.1 App information​

Fill in the basic app details:

  • App name — what users see on Google's consent screen (for example, "Harmony — Gmail").
  • User support email — a contact address users can reach if something goes wrong with authorization.

5.2 Audience​

Select External as the audience type so anyone in your organization (and any guest users you invite) can authorize the app.

5.3 Contact information​

Provide the required developer contact email addresses. Google sends notifications about your OAuth app — such as verification updates or policy issues — to these addresses.

5.4 Finish​

Review all the information and click Create to complete the Google Auth Platform setup.

Step 6. Add the required scopes​

Copy the scopes shown in the Harmony setup form and paste them into the Google Auth Platform configuration, then save the selected scopes.

The setup form lists the minimum scopes the Gmail integration needs. Adding fewer scopes will cause features such as reading messages, drafting replies, or sending email to fail. Adding extra scopes is unnecessary and may delay Google's app verification.

Step 7. Create the Client ID and Client Secret​

Step 7.1 Choose application type​

Set the application type to Web application and give it a recognizable name — for example, "Harmony — Gmail".

Step 7.2 Set Authorized JavaScript origins​

Set Authorized JavaScript origins to:

https://app.heyharmony.com

Step 7.3 Set Authorized redirect URIs​

Set Authorized redirect URIs to the value shown in the Harmony setup form. For Google Email this is:

https://app.heyharmony.com/integrations/oauth/gmail/callback

Google compares the redirect URI character-for-character at sign-in time. A trailing slash, an extra path segment, or http:// instead of https:// will cause the authorization to fail with an "Access blocked: invalid request" error.

Step 7.4 Copy the Client ID and Client Secret​

After clicking Create, Google shows a panel with your Client ID and Client Secret. Copy both values — you will paste them back into Harmony in the next step.

Treat the Client Secret like a password. Anyone with both the Client ID and Client Secret can impersonate the integration. If a secret leaks, rotate it in Google Cloud and update it in Harmony.

Step 8. Paste the credentials into Harmony​

Return to the Harmony setup form and paste the Client ID and Client Secret into the matching fields, then save.

Once saved, Harmony shows a summary of the configured application on the right side of the integration page so you can confirm the values at a glance.

From now on, anyone in your organization who connects Gmail from Marketplace → Apps → Google Email will be routed through your OAuth application. Each user signs in with their own Google account and grants access to their own mailbox — Harmony does not share inboxes between users.

What the Gmail integration unlocks​

Once a user connects Gmail, Harmony and Companion can:

  • Search and read recent messages to ground answers in real email context (with the user's permission).
  • Draft replies and new messages from meeting action items or Companion threads — drafts are saved to the user's own Gmail account for review before sending.
  • Send email when the user explicitly approves an action (Companion asks for confirmation before sending unless the user has set up an auto-approval rule).
  • Look up senders and threads as part of cross-tool workflows in Companion.

Gmail data is scoped to the individual user who connected it. Connecting Gmail at the workspace level only stores the OAuth application credentials — it does not give admins access to anyone's inbox.

Troubleshooting​

  • "Access blocked: This app's request is invalid" — the Authorized redirect URI in Google Cloud does not exactly match the one shown in the Harmony setup form. Re-check the URI character-for-character, including the /integrations/oauth/gmail/callback path.
  • "Error 403: access_denied" after authorization — one or more required scopes were not added on the OAuth consent screen, or the Gmail API was not enabled in Step 4. Re-check the scope list and that the API is enabled in the same project as the OAuth client.
  • Authorization succeeds but Gmail actions still fail — confirm that the Gmail API is enabled on the same Google Cloud project the OAuth credentials belong to, not a sibling project.
  • You need to rotate the secret — generate a new client secret in Google Cloud, then update it in the Harmony setup form. The Client ID can stay the same; existing user connections do not need to be rebuilt.
  • "This app isn't verified" warning shown to users — while your OAuth app is still in Testing or pending Google verification, users see an "unverified app" screen. They can still continue if they trust the workspace. For production rollout, submit the app for verification from the Google Auth Platform page.