Follow this general procedure when building a Gmail add-on:
- Create an Apps Script project.
- Configure the add-on project manifest.
- Write code to define the add-on's appearance and behavior, using the built-in Apps Script Card service.
- Deploy the add-on.
- Test the add-on within Gmail.
- 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 code or settings because the owner of the project left your 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 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.
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
class. Each card requires a
and one or more
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
After you have added all the sections and widgets to your card via its
CardBuilder, you must call
to create the corresponding
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.
When building a card, you must build from the top up. That is, you must use this construction order:
- Build the widget.
- Add the widget to card section.
- Repeat until the card section has all of its widgets.
- 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.
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.
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.
See Publishing an Gmail add-on for more details.