Building 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.
  6. Publish the add-on.

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.


When you colloborate with others in developing an add-on, a single user account owns the add-on project. 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's code or settings because the owner of the project left your organization.

To prevent losing access to add-on code, we encourage you to use shared drives when you collaborate on an add-on. Placing your add-on script file in a shared 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 (GCP) 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 Manifests 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. You can add universal actions to your add-on as well.

As you code, refer to the Gmail 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 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 what card is being displayed.

You can structure your add-on to use only universal actions, only a contextual trigger, only a compose trigger, or some combination thereof. 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 test a Gmail add-on, you must choose or create a deployment. For general testing, it's best to use the head deployment that is automatically created for the script project. If you are attempting to publish the add-on, you must create a versioned deployment prior to publishing.

Once you've chosen which deployment to use, you must look up its deployment ID. This ID is required to install the add-on for testing.

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.

See Testing Gmail add-ons for details.

Publish the add-on

Publishing your add-on makes it available to others, either publicly or just users in your domain. Before you start the publishing process, be sure to review the publication overview.

Gmail add-ons are published to the G Suite Marketplace. Publicly available add-ons must complete add-on review before they are published.

See Publishing an Gmail add-on for more details.