Best practices

Improve your users' overall experience by following these guides for add-on design.

Use just a few cards

If your add-on primarily uses basic navigation and displays more than a handful of cards, users cannot easily navigate and find information. If the add-on uses card stack navigation, having too many cards can make the navigation configuration complex and difficult to create and manage.

Avoid the impulse to create more cards than necessary.

Use widget creation functions

When writing code that creates Card or other complex UI objects, consider putting that code in its own function. This creation function should just build the object and return it. This lets you quickly regenerate that object whenever the UI must be refreshed. Remember to call build() after using the builder classes in the Card service.

Keep cards simple

If a given card has too many widgets, it can fill too much of the screen and become less useful. While large card sections render as collapsable UI elements, this hides information from the user. Aim to streamline your add-on and provide exactly what the user needs and no more.

Use error cards

Create cards for error conditions. If your add-on produces an error, it should display a card with the error information and instructions on how to correct it if possible. For example, if your add-on could not connect to a non-Google service because the authorization failed, display a card stating this and ask the user to verify the account information being used.

Write tests and test messages

You should thoroughly test all the add-ons you create. Build test functions that create cards and widgets using test data, and then verify that the objects are created as expected.

When using action callback functions, you usually must construct a response object. You can use statements like the following to verify that the responses are being constructed correctly:


Run test functions you create directly from the Apps Script editor using the Run menu. When you have a viable add-on working, be sure to install the unpublished version so you can test it in the Gmail UI.

You are likely to need a few test emails and their message IDs so that you can ensure that the add-on functions as expected when given different message content. You can get the message ID for a given message by listing messages using the Gmail API Users.messages.list method, or by making use of Apps Script's Gmail service.

Avoid relying too much on libraries

Using Apps Script libraries can cause your add-on to run more slowly than it would if all the Apps Script code were contained within a single script project. Although Apps Script libraries work in add-ons, you may run into performance reductions if you use them. Avoid including unnecessary libraries in your project, and consider ways to reduce your add-on's reliance on them.

Send feedback about...

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