Build Gmail Add-ons

Follow this general procedure when building a Gmail add-on:

  1. Create an Apps Script project.
  2. Configure the add-on project manifest.
  3. Write code to define the add-on's appearance and behavior, using the built-in Apps Script Card service.
  4. Deploy the add-on.
  5. Test the add-on within Gmail.

Create a script project

A Gmail add-on is a standalone Apps Script project. The standalone script guide provides instructions to create new projects. You can also just open a new script. If you do this, the project file (initially named Untitled project) is placed in your root Drive folder.

Configure the add-on project manifest

The add-on project manifest is a special JSON file used in Apps Script projects. It specifies a variety of details about the project, such as its library dependencies. For Gmail add-ons, the manifest also provides the basic information Gmail needs to display the add-on correctly.

See the Manifests guide for details on how to configure your add-on's manifest.

Code the add-on

Once you have created a script project, you can begin writing code to define the add-on appearance and behavior. You use the Apps Script Card service to construct the add-on user interface.

Contextual triggers

Gmail add-ons define a contextual trigger in their manifests. When the user opens a Gmail message that meets the trigger criteria* the trigger fires. A fired trigger executes an Apps Script trigger function that constructs the add-on user interface and returns it for Gmail to display. At that point the user can begin interacting with it.

Contextual triggers are defined in your add-on's project manifest. The trigger definition tells Gmail which trigger function to fire under which trigger criteria. For example, this manifest snippet sets an unconditional trigger that calls the trigger function getContextualAddOn():

  "gmail": {
    "name": "Quickstart Toolbar Label",
    "logoUrl": "https://www.example.com/hosted/images/2x/my-icon.png",
    "primaryColor": "#4285F4",
    "secondaryColor": "#4285F4",
    "contextualTriggers": [{
      "unconditional": {},
      "onTriggerFunction": "getContextualAddOn"
    }],
    "version": "TRUSTED_TESTER_V2"
  }

Trigger function

Every contextual trigger must have a corresponding trigger function that constructs your add-on's user interface. You specify this function in your manifest's onTriggerFunction field. You implement this function to accept a string message ID argument and return an array of one or more built Card objects.

When a contextual trigger fires for a given Gmail message, it calls this function and passes it an action event object. Often trigger functions use the message ID provided by this event object to get the message text and other details using Apps Script's Gmail service. For example, your trigger function could extract message content using these functions:

  // Activate temporary Gmail add-on scopes, in this case to allow
  // message metadata and content to be read.
  var accessToken = e.messageMetadata.accessToken;
  GmailApp.setCurrentMessageAccessToken(accessToken);

  var messageId = e.messageMetadata.messageId;
  var message = GmailApp.getMessageById(messageId);
  var subject = message.getSubject();
  var sender = message.getFrom();
  var body = message.getPlainBody();
  var messageDate = message.getDate();
  var thread = message.getThread();

The trigger function can then act on this data, extracting the information that it needs for the interface. For example, an add-on that summarizes sales numbers can collect sales figures from the message body and organize them for display in a card.

The trigger function must build and return an array of built Card objects. For example, the following builds an add-on with a single card that just lists the subject and sender of the message:

  function getContextualAddOn(e) {
    // Activate temporary Gmail add-on scopes, in this case to allow
    // message metadata to be read.
    var accessToken = e.messageMetadata.accessToken;
    GmailApp.setCurrentMessageAccessToken(accessToken);

    var messageId = e.messageMetadata.messageId;
    var message = GmailApp.getMessageById(messageId);
    var subject = message.getSubject();
    var sender = message.getFrom();

    // Create a card with a single card section and two widgets.
    // Be sure to execute build() to finalize the card construction.
    var exampleCard = CardService.newCardBuilder()
        .setHeader(CardService.newCardHeader()
            .setTitle('Example card'))
        .addSection(CardService.newCardSection()
            .addWidget(CardService.newKeyValue()
                .setTopLabel('Subject')
                .setContent(subject))
            .addWidget(CardService.newKeyValue()
                .setTopLabel('From')
                .setContent(sender)))
        .build();   // Don't forget to build the Card!
    return [exampleCard];
  }

Constructing cards

You define an add-on user interface by creating Card objects and filling them with widgets. Your trigger function must return an array of one or more Card objects that represent the initial state of the add-on. Your add-on can also create and display new cards in response to user actions.

You create cards using the CardBuilder class. Each card requires a CardHeader and one or more CardSections. You should populate each card section with the individual widgets that make up the add-on interface. Interaction widgets, are usually linked to actions to define their interaction behavior.

After you have added all the sections and widgets to your card via its CardBuilder, you must call CardBuilder.build() to create the corresponding Card object.

You can use other built-in Apps Script services such as CalendarApp to retrieve information to display in the add-on cards you build. You can use data fetched from non-Google services.

If your Gmail add-on needs access to non-Google APIs that require OAuth, you must configure and connect to that service—see the Connecting to Non-Google Services guide for more details.

Construction order

When building a card, you must build from the top up. That is, you must use this construction order:

  1. Build the widget.
  2. Add the widget to card section.
  3. Repeat until the card section has all of its widgets.
  4. Add the card section to the card.

This is required because when you add a widget to a card or card section, you are actually adding a copy of that widget. Any changes you make to the widget object after adding it are not reflected in the final card.

Universal actions

You can use universal actions to provide context-independent functionality. Universal actions are menu items available in the add-on UI regardless of what Gmail message is currently open or what card is being displayed.

You can structure your add-on to use only universal actions, only a contextual trigger, or a combination of the two. All defined universal actions always appear in the add-on's card menu. If a contextual trigger doesn't fire after a Gmail message opens, Gmail automatically displays a list of any universal actions defined for the add-on instead of opening a specified card. See Universal actions for more details.

Deploy the add-on

Before you can use a Gmail add-on, you must choose a deployment. You can then install the add-on in development mode. See the installation guide for specific instructions.

Test the add-on

You can test installed development add-ons by opening a relevant Gmail message and inspecting the response. You can verify that the add-on behaves as expected for different message content by creating a collection of test messages in your Gmail inbox and opening the add-on for each one.