Building a Gmail add-on

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.

Collaboration

When you colloborate with others in developing an add-on, the add-on project is owned by a single user account. When you publish an add-on, a single user account acts as the publisher. The publishing account must have edit access to the add-on script project, but it doesn't need to be project owner.

It's very important to avoid situations where you lose access to an add-on code or settings because the owner of the project left our organization!

To prevent this, we encourage you to use Team Drives when you collaborate on an add-on. Placing your add-on script file in a Team Drive ensures that no single account is the sole owner of the project.

It is also recommended that you add collaborators to the script project's Cloud Platform project. This helps ensure someone on your team always can access the add-on's Cloud settings.

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.

A Gmail add-on can implement a UI to assist users who are reading messages, a UI to assist users who are creating message drafts, or both. Universal actions can be added as well.

As you code, refer to the Add-on style guide for guidelines on how to design your add-on user experience.

Extending the message interface

Gmail add-ons can extend the Gmail message interface (the message UI) that appears when a users opens a message to view it. To do this, you must define a contextual trigger for your add-on. This trigger fires when a message is opened, and executes an associated trigger function to build an add-on UI.

See Extending the message UI for more details.

Extending the compose interface

Gmail add-ons can also extend the Gmail compose interface (the compose UI) that appears when a users is creating a new draft or reply. An add-on can add a Compose action to the compose window which, when selected, executes a compose trigger function to build a custom interace you design.

See Extending the compose UI with compose actions for more details.

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.

See the installation guide for specific instructions.

Test the add-on

You can test installed development add-ons with message UIs 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.

You can test development add-ons with Compose actions by composing messages. Be sure to test the add-on when composing new messages and replies to existing messages.

Send feedback about...

Gmail Add-ons
Gmail Add-ons
Need help? Visit our support page.