Quickstart: Gmail Add-on

Complete the steps described in the rest of this page, and in about five minutes you'll have created a Gmail add-on.

Prerequisites

To run this quickstart, you need the following:

A Google account with Gmail enabled.
Access to Google Drive.

Step 1: Create the script project

Create a new Apps Script project in your web browser. Apps Script places the project file in your Drive root folder so you can find it later.
Choose Blank Project if presented with a welcome screen.

Replace the Code.gs file contents with the following:

/**
 * Copyright Google LLC
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * Returns the array of cards that should be rendered for the current
 * e-mail thread. The name of this function is specified in the
 * manifest 'onTriggerFunction' field, indicating that this function
 * runs every time the add-on is started.
 *
 * @param {Object} e The data provided by the Gmail UI.
 * @return {Card[]}
 */
function buildAddOn(e) {
  // Activate temporary Gmail add-on scopes.
  var accessToken = e.messageMetadata.accessToken;
  GmailApp.setCurrentMessageAccessToken(accessToken);

  var messageId = e.messageMetadata.messageId;
  var message = GmailApp.getMessageById(messageId);

  // Get user and thread labels as arrays to enable quick sorting and indexing.
  var threadLabels = message.getThread().getLabels();
  var labels = getLabelArray(GmailApp.getUserLabels());
  var labelsInUse = getLabelArray(threadLabels);

  // Create a section for that contains all user Labels.
  var section = CardService.newCardSection()
    .setHeader("<font color=\"#1257e0\"><b>Available User Labels</b></font>");       

  // Create a checkbox group for user labels that are added to prior section.
  var checkboxGroup = CardService.newSelectionInput()
    .setType(CardService.SelectionInputType.CHECK_BOX)
    .setFieldName('labels')
    .setOnChangeAction(CardService.newAction().setFunctionName('toggleLabel'));

  // Add checkbox with name and selected value for each User Label.
  for(var i = 0; i < labels.length; i++) {
    checkboxGroup.addItem(labels[i], labels[i], labelsInUse.indexOf(labels[i])!= -1);
  }

  // Add the checkbox group to the section.
  section.addWidget(checkboxGroup);

  // Build the main card after adding the section.
  var card = CardService.newCardBuilder()
    .setHeader(CardService.newCardHeader()
    .setTitle('Quick Label')
    .setImageUrl('https://www.gstatic.com/images/icons/material/system/1x/label_googblue_48dp.png'))
    .addSection(section) 
    .build();

  return [card];
} 

/**
 * Updates the labels on the current thread based on 
 * user selections. Runs via the OnChangeAction for
 * each CHECK_BOX created.
 *
 * @param {Object} e The data provided by the Gmail UI.
*/
function toggleLabel(e){
  var selected = e.formInputs.labels;

  // Activate temporary Gmail add-on scopes.
  var accessToken = e.messageMetadata.accessToken;
  GmailApp.setCurrentMessageAccessToken(accessToken);

  var messageId = e.messageMetadata.messageId;
  var message = GmailApp.getMessageById(messageId);
  var thread = message.getThread();

  if (selected != null){
     for each (var label in GmailApp.getUserLabels()) {
       if(selected.indexOf(label.getName()) != -1){
          thread.addLabel(label);
       }
       else {
         thread.removeLabel(label);
       }
     }
  }
  else {
    for each (var label in GmailApp.getUserLabels()) {
      thread.removeLabel(label);
    }
  }
}

/**
 * Converts an GmailLabel object to a array of strings. 
 * Used for easy sorting and to determine if a value exists.
 *
 * @param {labelsObjects} A GmailLabel object array.
 * @return {lables[]} An array of labels names as strings.
*/
function getLabelArray(labelsObjects){
  var labels = [];
  for(var i = 0; i < labelsObjects.length; i++) {
    labels[i] = labelsObjects[i].getName();
  }
  labels.sort();
  return labels;
}

quickstart.gs

Click File > Save, name your project "Gmail Add-on Quickstart", and click OK.

Step 2: Update the script manifest

In the script editor, select the View > Show manifest file menu item. This opens the manifest file (appsscript.json) in the editor.

Delete the content of the manifest and replace it with the following:

{
  "oauthScopes": [
    "https://www.googleapis.com/auth/gmail.addons.execute",
    "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
    "https://www.googleapis.com/auth/gmail.modify" 
  ],
  "gmail": {
    "name": "Gmail Add-on Quickstart - QuickLabels",
    "logoUrl": "https://www.gstatic.com/images/icons/material/system/1x/label_googblue_24dp.png",
    "contextualTriggers": [{
      "unconditional": {
      },
      "onTriggerFunction": "buildAddOn"
    }],
    "openLinkUrlPrefixes": [
      "https://mail.google.com/"
    ],
    "primaryColor": "#4285F4",
    "secondaryColor": "#4285F4"
  }
}
appsscript.json

Select File > Save to save these changes to the manifest. This step provides the add-on with required deployment information.

Step 3: Deploy the add-on

In the script editor, select Publish > Deploy from manifest....
In the Deployments dialog, click the Get ID link for the Head Deployment.
Locate the head deployment the Deployment ID. Copy this ID and then click Close.
In the Deployments dialog, click Close. Creating a new deployment is not necessary, as you are using the head deployment only.
Open the Gmail add-on settings tab.
In the Add-ons tab, ensure that you have selected the Enable developer add-ons for my account checkbox.
Paste your add-on's deployment ID into the Install developer add-on textbox and click Install.
In the Install developer add-on dialog that appears, click the checkbox to indicate that you trust this developer (yourself), then click Install.

When you have completed these steps, the add-on appears in the Developer add-ons list and becomes available for use in Gmail.

Step 4: Run the add-on

On a desktop device, open Gmail. You may need to refresh the tab if Gmail is already open.
Choose a message in Gmail and open it.
Your installed add-ons appear as a column of icons to the right of the open email thread. Click on the bookmark icon that corresponds to the "Gmail Add-on Quickstart" you just installed.
The add-on should place a contextual card on the right-side of the window, with a message asking for authorization. Click the Authorize access link to open a dialog where you can authorize the add-on.
Select the account that should authorize the add-on.
The next dialog may inform you that the app is not verified. In this case you can proceed by doing the following:
1. Click Advanced.
2. At the bottom of the dialog, click Go to Gmail Add-on Quickstart (unsafe).
3. In the new dialog, type "Continue" into the text field, then click Next.
Read the notice in the next dialog carefully, then click Allow.
Once authorized, the add-on should automatically refresh and start operating.

Publish

Since this is an example add-on, this tutorial ends here. If you were developing a real add-on, the last step would be to publish it for other people to find and install.