How to Build Custom Google Workspace Add-ons

Google Workspace Add-ons are powerful ways to enhance Gmail, Calendar, Drive, Docs, and other Workspace tools. If you're a developer, you can create your own custom add-ons using Google Apps Script and deploy them privately or publicly via the Marketplace.

In this guide, you'll learn:

• The difference between Editor Add-ons and Workspace Add-ons
• How to build your own Workspace Add-on using Cards API and clasp (Command Line Apps Script Projects)

---

🆚 Workspace vs Editor Add-ons

Before diving into development, it's important to understand the two main types of Google add-ons:

🟢 Google Workspace Add-ons

• Appear in the sidebar of Gmail, Calendar, Drive, etc.
• Use the Cards API for UI
• Designed for context-aware actions, like accessing metadata from an email or file
• Can be pinned to the sidebar across multiple apps
• Installed and managed via the Google Workspace Marketplace

🟣 Editor Add-ons

• Built specifically for Google Docs, Sheets, Slides, or Forms
• Appear in the top menu bar (Extensions > Add-ons)
• Use HTML Service or sidebars/dialogs built in custom HTML/JS
• More flexible UI options, but less native integration

TL;DR:
Use Workspace Add-ons when you want a unified, card-style experience across Gmail, Calendar, etc.
Use Editor Add-ons for in-doc workflows, custom menus, and advanced UI flexibility.

---

🧰 Prerequisites

Before starting, make sure you have:

• A Google account
• clasp installed (npm install -g @google/clasp)
• Access to Google Apps Script
• Basic JavaScript knowledge

---

🛠️ How to Build a Google Workspace Add-on (with Cards API)

We'll use clasp to build a sidebar-based Workspace Add-on that can run in Gmail.

Step 1: Create a New Project Folder

mkdir my-addon
cd my-addon
clasp create --type standalone --title "My Workspace Add-on"

This will create a new Apps Script project.

---

Step 2: Add the Required Files

📄 appsscript.json

{
  "timeZone": "America/New_York",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "My Custom Add-on",
      "logoUrl": "https://example.com/logo.png",
      "layoutProperties": {
        "primaryColor": "#4285F4"
      },
      "useLocaleFromApp": true,
      "homepageTrigger": {
        "runFunction": "onHomepage"
      }
    },
    "gmail": {
      "contextualTriggers": [{
        "unconditional": {},
        "onTriggerFunction": "buildGmailCard"
      }],
      "composeTrigger": {
        "selectActions": [{
          "text": "Insert template",
          "runFunction": "onInsertTemplate"
        }]
      }
    }
  }
}

---

Step 3: Write the Add-on Code (Cards API)

📄 Code.js

function onHomepage(e) {
  return buildCard("Welcome to your Add-on!");
}

function buildGmailCard(e) {
  return buildCard("You opened an email!");
}

function buildCard(text) {
  const card = CardService.newCardBuilder();
  const section = CardService.newCardSection();
  const widget = CardService.newTextParagraph().setText(text);
  section.addWidget(widget);
  card.addSection(section);
  return card.build();
}

---

Step 4: Deploy and Test

clasp push
clasp open

• This opens your project in the Google Apps Script editor
• From there, go to Deploy > Test deployments > Install add-on
• It will now appear in Gmail’s sidebar

---

✨ Tips

• Use CardService.newTextInput(), newButtonSet(), etc. to create forms and actions
• Each function must return a Card or ActionResponse
• Test in Gmail first, then expand to Calendar or Drive as needed

---

📦 Publishing Options

• Internal use: Share with your Workspace domain only (no approval needed)
• Public release: Submit to the Google Workspace Marketplace (requires OAuth screen review and compliance checks)

More info: Publish Add-ons

---

🧠 Summary

Feature	Workspace Add-ons	Editor Add-ons
Appears In	Gmail, Calendar, etc.	Docs, Sheets, Slides
UI Framework	Cards API	HTML Service
Installation Method	Sidebar (Marketplace)	Menu (Extensions > Add-ons)
Context Awareness	Yes	Limited
Best For	CRM, productivity, tasks	Templates, calculations

---

Building Google Workspace Add-ons is a great way to automate workflows and deliver rich experiences inside the tools your users already use. Start with the Cards API for sidebar add-ons — it’s structured, clean, and widely supported.

Need inspiration? Explore popular add-ons at AddonsHunt.com