Google Workspace - Gmail Add-On installation

This guide is for a Google Workspace administrator installing the InTouch Gmail add-on for your organisation. You deploy the add-on inside your own Google Workspace, using the bundle InTouch provides. Because the add-on runs entirely within your domain, you authorise it for your own users, the same way you would any internal Apps Script.

You will need:

  • A super-administrator account for your Workspace domain.
  • The two files InTouch gave you, delivered in a folder named for the version (e.g. InTouch-Gmail-Addon-1.0.56/):
    • index.js — the add-on code bundle.
    • appsscript.json — the add-on manifest (permissions and configuration).
  • About 20–30 minutes.

Getting the files: contact support@intouch.cloud for the latest files required for this setup — the InTouch Gmail add-on index.js and appsscript.json.

An InTouch account is still required for your users — the add-on is a client that talks to InTouch’s service. This guide only covers installing the add-on itself.

If you are having difficulties following these instructions, please contact support@intouch.cloud and we can schedule a session to work through it with you.

The five steps at a glance:

  1. Create the Apps Script project — paste the code + manifest.
  2. Attach a standard Google Cloud project — needed to publish privately.
  3. Configure the OAuth consent screen — set audience to Internal.
  4. Enable the Marketplace SDK and create the listing — deploy, then list the add-on privately.
  5. Install it for your users — push it out from the Admin console.

Steps 1–4 are one-time setup. After that, updating to a new version is just two clicks.

Step 1 — Create the Apps Script project

  1. Go to https://script.google.com and click New project.
  2. Rename the project (top left) to something like InTouch Gmail Add-on.
  3. In the default Code.gs file, delete the placeholder contents.
  4. Paste in the entire contents of index.js and save (⌘/Ctrl+S).
  5. Show the manifest: open Project Settings (⚙️ gear, left sidebar) and tick “Show ‘appsscript.json’ manifest file in editor”.
  6. Back in the Editor, open the appsscript.json file.
  7. Replace its contents with the appsscript.json InTouch gave you. Save.

Step 2 — Attach a standard Google Cloud project

  1. In https://console.cloud.google.com, create a new project (top bar project selector → New Project), e.g. InTouch Gmail Add-on.
  2. Note its Project number (Cloud Console → IAM & Admin → Settings).
  3. Back in the Apps Script editor, go to Project Settings (⚙️) → under Google Cloud Platform (GCP) Project click Change project.
  4. Paste the project number and confirm.

Google recently renamed the “OAuth consent screen” to the Google Auth Platform, and split its settings across a few pages. In the Cloud Console (same project from Step 2, confirm it’s selected in the top bar) go to APIs & Services → OAuth consent screen (this redirects into the Google Auth Platform), or open it directly at https://console.cloud.google.com/auth/overview. If the project has never been configured, click Get started and it walks you through the fields below.

  1. Go to the Audience page and set User type: Internal. (Internal keeps the add-on private to your domain. If Internal is greyed out or missing, the GCP project wasn’t created inside your Workspace organisation — recreate it under your intouch.cloud org, not a personal account.)
  2. Go to the Branding page.
  3. Set the App name (e.g. InTouch).
  4. Set the User support email.
  5. Set the Developer contact email (support@intouch.cloud).
  6. Click Save.
  7. You do not need to touch the Data Access / Scopes page by hand — the scopes come from the manifest at deploy time.

Step 4 — Enable the Marketplace SDK and create the listing

  1. Cloud Console → APIs & Services → Library → search Google Workspace Marketplace SDK → Enable.
  2. Create the deployment first — the listing needs its ID. In the Apps Script editor → Deploy → New deployment → gear icon → select Add-on → Deploy.
  3. Copy the Deployment ID it shows. (Do this before the next steps; the App Configuration tab won’t save without an ID to paste.)
  4. Open the SDK’s own page: type Google Workspace Marketplace SDK into the Cloud Console top search bar and open the result (or APIs & Services → Enabled APIs & services → click it in the list). Open the App Configuration tab — it lives on this page, not under the main APIs menu.
  5. Set App Visibility to Private (My organization / your domain only).
  6. Under App Integrations, tick Google Workspace add-on, then select the Apps Script radio below and paste the Deployment ID from step 3.
  7. Fill the required developer name and link fields (developer name, website, privacy policy URL, terms URL).
  8. Click Save.

    You might see a red note under the Google Workspace add-on checkbox: “Google Workspace add-ons can only be bundled with Drive apps and Docs, Sheets, Slides, Forms and Classroom add-ons.” Ignore it — it is not an error and does not block saving. It only concerns bundling with Editor add-ons; a Gmail add-on is fully supported. As long as Apps Script is selected and the Deployment ID is filled in, Save works. If Save is greyed out, it’s because the Deployment ID or a required developer field is empty — not because of that note.

  9. Open the Store Listing tab and add the app name, a short description, an icon, and at least one screenshot. The icon and screenshot are both Google-required — Publish stays disabled until they’re filled. Use the InTouch assets (the icons display correctly on both light and dark Gmail themes):
    • Icon 128×128: https://static.intouch.cloud/images/logos/intouch-darkmode-safe-128.png
    • Icon 512×512: https://static.intouch.cloud/images/logos/intouch-darkmode-safe-512.png
    • Screenshot: https://static.intouch.cloud/images/gmail-add-on/Login-Panel.png
  10. Publish. For a private app this publishes directly to your organisation.

Step 5 — Install it for your users

As a super-admin at https://admin.google.com:

  1. Go to Apps → Google Workspace Marketplace apps → Apps list → Add app → Search apps. Your private app appears under your organisation. (Or use the admin install link shown on the Store Listing in Step 4.)
  2. Choose to install for everyone or for a specific organisational unit / group.
  3. Accept the requested permissions on your organisation’s behalf and Finish.

The InTouch panel will appear in users’ Gmail right-hand sidebar. Propagation is usually a few minutes and can take up to 24 hours.

Updating to a new version

InTouch ships updates as a new index.js bundle (with a higher version on the first line). To roll out an update:

  1. In the Apps Script editor, replace Code.gs with the new index.js. Save.
  2. Deploy → Manage deployments → edit your add-on deployment → create a New version → Deploy.

Users pick up the new version automatically — no reinstall needed. You can confirm which version is live by checking the footer at the bottom of the InTouch panel in Gmail; it should match the version on the first line of the bundle you pasted.

Troubleshooting

  • “This app isn’t verified” warning when installing — this means the Audience was set to External instead of Internal (Step 3.1). Internal apps shown to your own domain are not warned about.
  • Can’t tick “Internal” on the Audience page — the GCP project isn’t under your Workspace organisation. Recreate the project inside your intouch.cloud org (Step 2) and re-do Step 3.
  • Red “can only be bundled with Drive/Docs…” note in App Integrations — this is informational, not an error. See the note in Step 4; saving still works.
  • Add-on doesn’t appear in Gmail — confirm the admin install (Step 5) targeted the user’s organisational unit, and allow up to 24h. Have the user fully reload Gmail.
  • Wrong/old version showing — re-check Step “Updating”: pasting a new bundle is not enough; you must also create a new deployment version.

Feedback

We know this setup involves a lot of steps across Google’s consoles, and we’d like to make it smoother. If you spotted a way to improve the process — please tell us at support@intouch.cloud. Your feedback directly shapes how we refine this guide.

<< Previous     
Powered by HelpDocs (opens in a new tab)