Gmail Add-on + Workspace Marketplace + Service Account (DWD)

DIY End-to-End Onboarding Guide

Who This Guide Is For

1. Developers building and deploying a Gmail add-on with Google Apps Script.
2. Admins rolling out an add-on org-wide via Google Workspace Marketplace.
3. Backend engineers setting up a Service Account with Domain-wide Delegation (DWD).
   

Time to Complete

1. Basic test install: 20–30 minutes
2. Private (org) rollout: 30–45 minutes
3. Public Marketplace listing: 1–3 days (includes Google review)
   

Prerequisites

1. Google Workspace admin rights (for org rollout and DWD).
2. A Google account (any) for personal testing.
3. Your Apps Script add-on code (e.g., function getContextualAddOn).
   

Step 1: Create your Google Cloud Project (the foundation)

1. Open https://console.cloud.google.com/ and click the project selector (top bar).
2. Click “New Project”, give it a name (e.g., TPIR-Gmail-Addon), and create it.
   

1. Copy down the Project Number (you’ll need it when linking Apps Script).
   

1. Enable required APIs (in THIS project): Gmail API; Google Apps Script API; Google Workspace Marketplace SDK; Google Workspace Marketplace integration client; Admin SDK (only if backend uses Directory); Google Workspace Add-ons.
   

Tip: Keep a simple table of all IDs (Project Number, Script ID, Deployment ID, etc.) for quick reference.

Step 2: Set up the Apps Script project

1. Open https://script.google.com/, click “New project” and paste your add‑on code (Code.gs).
   

Note: Make sure the projects are under the same name in appsscript and google cloud console

1. Apps Script → Project settings (gear) → tick “Show appsscript.json manifest file in editor”.
   

1. Open appsscript.json and paste the minimal manifest (below).
   

1. Minimal Manifest (appsscript.json)
   

1. Do NOT click Run on getContextualAddOn from the editor—this only works inside Gmail.
2. Add additional hosts to urlFetchWhitelist if your add‑on calls more external APIs (optional if you have any extra APIs other than mentioned).
3. Link the Apps Script to your Cloud Project: Apps Script → Project → Project settings → Google Cloud Platform (GCP) project → Change project, then paste the Project Number.
   

Step 3: Configure OAuth consent screen

1. Cloud Console (same project) → APIs & Services → OAuth consent screen.
   

1. Fill App name, support email, developer contact.
2. Choose User type: Internal (Workspace‑only) (Client) or External (for public/testing).
3. Add the same scopes as in your manifest (see below).
4. If External and in testing, add your testers under “Test users”. Save.
5. Manifest scopes (copy) (Data Access):
   
1. https://www.googleapis.com/auth/gmail.addons.execute
2. https://www.googleapis.com/auth/script.external_request
3. https://www.googleapis.com/auth/gmail.modify
4. https://www.googleapis.com/auth/userinfo.email
   

Step 4: Google Workspace Marketplace Store Listing

1. Cloud Console (same project) → APIs & Services → Google Workspace Marketplace SDK → Store Listing.
   

1. Fill out the details.
   

1. Save Draft → Publish.
   

Step 5: Configure the Workspace Marketplace listing (App Configuration)

1. Cloud Console → APIs & Services → Google Workspace Marketplace SDK → App configuration.
   

1. Set App visibility: Private (org) or Public (Marketplace review).
   

1. App integrations → Google Workspace add‑on → Apps Script → paste the Deployment ID.
   

1. Add OAuth scopes (keep them minimal and consistent with the manifest).
   

1. Fill developer info, branding (logo/description). Click “Save draft”.
   

1. Distribution is controlled by “App visibility”.
2. If you enable a Web app icon, upload 96×96 and 48×48 PNG icons.
   

Step 6: Deploy Gmail Add‑on and verify in Gmail

1. Apps Script → Project → Deploy → New deployments → Select type “Gmail Add‑on”
   

1. Apps Script → Deploy → Manage deployments → copy the Deployment ID (AKfycb…).
   

Step 7: Install for everyone in your domain (Private visibility)

1. Google Admin Console (super admin) → Apps → Google Workspace Marketplace apps.
2. Find your private listing → Admin install / Force install for domain or specific OUs.
   

Note: If it is not visible yet, confirm App visibility is Private, same org, and wait a few minutes.

Step 8: Public Marketplace listing (optional)

1. Complete Store listing (logo, description, website).
2. Provide Privacy Policy & Terms of Service URLs.
3. Submit for Google review and address feedback if any.
   

Step 9: Backend Service Account with Domain‑wide Delegation (Optional)

1. Create a Service Account and key:
2. Cloud Console → IAM & Admin → Service accounts → Create account.
3. Grant minimal roles; create JSON key (store securely).
4. Authorize Domain‑wide Delegation (DWD):
5. Admin Console → Security → API controls → Manage domain‑wide delegation → Add new.
6. Client ID = Service Account’s numeric Client ID (from SA details page).
7. OAuth scopes (comma‑separated) matching your code’s scopes.
8. Scope sets (choose one):
   
1. Recommended (Gmail API + Directory read-only):
   
1. https://www.googleapis.com/auth/gmail.modify,https://www.googleapis.com/auth/admin.directory.user.readonly,https://www.googleapis.com/auth/admin.directory.group.readonly
2. Full Gmail (only if truly required):
1. https://mail.google.com/,https://www.googleapis.com/auth/admin.directory.user,https://www.googleapis.com/auth/admin.directory.group.readonly
3. Node.js example (JWT with impersonation):
   

1. API enablement (very important):
1. Enable Gmail API and Admin SDK in the SAME project as the service account.
2. If you see “Gmail API has not been used in project …”, enable and retry after a few minutes.
   

Step 10: Where to find each ID quickly

Step 11: Troubleshooting (copy‑paste fixes)

A) e.messageMetadata is undefined — Deploy and test in Gmail; do not run add‑on entrypoints from the editor.

B) Manage deployments spinner — Hard refresh, try incognito/another browser; console UI hiccup.

C) Add‑on not visible in Admin console — Ensure Private visibility, same org, and allow propagation time.

D) Two add‑ons appear — Remove older test deployment or uninstall from Admin console.

E) unauthorized_client on JWT — DWD missing/wrong Client ID or scopes don’t match code.

F) 403 accessNotConfigured — Enable Gmail API/Admin SDK in the service account's project; wait a few minutes.

G) redirect_uri_mismatch (only if making your own OAuth client for Script) — Use: https://script.google.com/macros/d/<YOUR_SCRIPT_ID>/usercallback