Publishing Gmail Add-ons

Publishing add-ons allows them to be used by others, who can access and install them from Gmail and from the G Suite Marketplace.

You can publish your add-on publicly, so that any Gmail user can find and install it. You can also publish add-ons privately, for users in a specific domain only. If you are a G Suite domain administrator, you can install published add-ons—whether public or private—for your domain users.

Once you've successfully published an add-on, you can continue to improve it—see Managing Published Add-ons for more information.

In addition to published add-ons, you can also install an unpublished add-on—this lets you test it or just use it youself without publishing.

Before you begin

Before you begin the publication process, it is important to understand your publishing options.


When configuring your add-on for publication, you must choose to publish it as either a private or public add-on. This is the add-on's visibility.

  • Private add-ons are only visible to users in the same domain as the add-on publishing account. Only domain accounts can publish private add-ons. They can't be installed by outside users. Private add-ons do not require add-on review. Private visibility is also referred to as My Domain visibility.
  • Public add-ons are visible globally in the G Suite Marketplace. Anyone can install them if their domain policies allow it. Public add-ons must go through the add-on review process before they are published. This review process can take a few days to complete, and may require you to make changes to your add-on code.

Individual installs

Domain administrators can install add-ons on behalf of some or all of their domain users. While configuring your add-on for publication, you can elect to also allow individual installs. If you do, both admins and individual users can install your add-on. However, a domain user may still be prevented from installing an add-on if their domain policies prohibit it.

Individual installs are enabled by default.


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.

We encourage you to use Team Drives when you collaborate on an add-on. This allows you to avoid losing access to your add-on's code and console settings because a member of your team left your organization. Alternatively, create a common team account to serve as the owner and publisher of the script project.

Publishing requirements

Before add-ons can be published publicly, they must be submitted to Google for add-on review. This process ensures that the add-ons available in the G Suite Marketplace meet quality and user protection guidelines.

Use the checklist below to make sure that your add-on passes the add-on review process. If you are publishing your add-on privately, you can still use this checklist to ensure your add-on provides a good user experience.

General requirements

Make sure your add-on meets the following general requirements before attempting to publish:

  • Completeness. The add-on must be fully functional. It can't be a “work in progress.”
  • Testing. The script has been tested with multiple active users as an unpublished add-on.
  • Naming. The script's project name is the same as the name intended for publication (the script name appears in the authorization dialog).
  • OAuth client verification. You have requested OAuth verification for add-on script project. This requires that you show ownership of a domain and that you have a privacy policy hosted within that domain.

  • Style. Follow the recommendations in the add-on style guide.

Technical requirements

Make sure your add-on meets the following technical requirements before attempting to publish:

  • Manifest. The add-on script project must include a well-defined manifest.
  • Libraries. The add-on does not use libraries unnecessarily, which can cause the add-on to run slowly in some cases.
  • Error handling. The add-on script has error-handling and shows relevant error messages to the user.
  • Hosted images. All users of the add-on can access any hosted image used in your add-on or its OAuth consent screen.
  • Versioned deployment. The add-on has a versioned deployment to be used for publication. Do not use head deployments for published add-ons. When you update your add-on, create a new script project version and edit the versioned deployment to use that version number.
  • Trigger function. If your add-on script uses a contextual trigger, it must have a well-defined trigger function implemented and specified in the project manifest.
  • Universal actions. Any universal actions defined in your add-on script must specified in the manifest and relate to context-independent actions.
  • OAuth flow. If your add-on connects to non-Google services using OAuth, ensure it handles the OAuth authorization flow correctly.

User data protection requirements

The following requirements help to ensure that user data is protected while they use your add-on. Any add-on that fails to sufficiently protect user information cannot pass review for publication.

  • Scopes. You must set explicit scopes in the add-on manifest, choosing the narrowest scopes possible. Never have the add-on ask the user for more permissions than it actually needs. See the Gmail add-on scopes section for a list of scopes often used with Gmail add-ons. Most of these require a temporary access token.
  • UrlFetch whitelist. If the add-on script uses UrlFetch to retrieve data, you must whitelist the URLs it accesses using the urlFetchWhitelist field in the add-on manifest. Restrict the URLs the add-on fetches to the following:
    • Legitimate third-party APIs,
    • Sets of private endpoints you control, and
    • Authorization endpoints that enable OAuth flows.
  • Open link whitelist. If your add-on script makes use of OpenLink actions, you must whitelist the URLs it opens using the gmail.openLinkUrlPrefixes field in the add-on manifest. This whitelist restricts what URLs the add-on can open. If your script code opens URLs that aren't whitelisted, you can't create or edit versioned deployments of your add-on. If your add-on functionality demands it, you can use a single * character as wildcard to match all links in the whitelist.

Marketplace listing asset requirements

In order to build your add-on's listing in the G Suite Marketplace, you must provide certain image, text, and URL assets for your add-on. Before beginning the publication process, compile all the assets needed for Marketplace listings.

If desired, you can update the add-on assets after publication by editing the listing.

Publish an add-on

Once you have fulfilled all the publication requirements for your add-on, you can publish it by completing the following steps:

Step 1: Create a versioned deployment

Create a versioned deployment of your add-on using the version of the code you want to publish. Your add-on can only have one versioned deployment, but you can change the script project version that it uses. Do not attempt to publish using a head deployment.

Once you've created a versioned deployment, select the Get ID link for that deployment in the Deployments dialog. This shows a new dialog containing the deployment description and the deployment ID.

During add-on authorization, users see a dialog that describes the requested permissions. You can customize this dialog to some extent by using the following steps:

  1. Open your add-on's Cloud Platform project.
  2. In the console's left navigation, select APIs & services to open the API dashboard.
  3. In the left nav, select Credentials to open the credentials control panel.
  4. In the credential control panel, select the OAuth consent screen tab.
  5. Fill in the consent screen form using the corresponding assets you collected. Some of the form elements are optional, but providing them can improve your add-on's user experience.
  6. Click Save to record your selections.

Step 3: Enable the Marketplace SDK

The G Suite Marketplace SDK lets you configure the appearance of your Marketplace listing. Enable the SDK in your add-on script project by doing the following:

  1. If you have not done so already, open your add-on's Cloud Platform project.
  2. In the console's left navigation, select APIs & services to open the API dashboard.
  3. In the API dashboard, select the Enable APIs and Services button.
  4. In the Search for APIs & services search bar, type "Apps Marketplace SDK". Select this API.
  5. In the API listing that opens, click the Enable button. After a moment the SDK overview control panel opens.

You have now enabled the G Suite Marketplace SDK for your script project. Now you can use the SDK control panel to configure the SDK.

Step 4: Configure the Marketplace SDK

The G Suite Marketplace SDK settings page has four panels: Overview, Configuration, Publish, and Usage. To define your add-on's listing and start a publication request, you must do the following:

  1. If it isn't open already, open the Marketplace SDK control panel Select the Configuration panel. This panel contains a form where you provide information about your add-on.
  2. Fill in the configuration form using the corresponding assets you collected. Some of the form elements are optional, but providing them can improve your add-on's user experience. Do the following as you are completing the form:
    • Where indicated, provide localized assets for each language you intend to publish the add-on in.
    • Check the Enable individual install checkbox if you want to allow individual installs.
    • Where indicated, include every scope listed in your add-on project's manifest.
    • In the Extensions section, only check the Gmail add-on extension checkbox. This causes a text field to appear. In this textbox, enter the deployment ID for the versioned deployment you created.
    • If your are publishing from a domain account, select your add-on's visibility where indicated. Selecting My Domain makes your add-on a private add-on. Warning: Once you choose a visibility option and save, you can't change your selection later.
  3. Verify that the information you have entered in the form is correct, then click Save changes.
  4. Select the Publish panel, and fill out form there using the corresponding assets you collected. Some of the form elements are optional, but providing them can improve your add-on's user experience. Do the following as you are completing the form:
    • Where indicated, provide localized assets for each language you intend to publish the add-on in.
    • In the Reach section, select an appropriate category for your add-on to help upers locate it in the Marketplace. Also select the regions and countries where you want Marketplace to present your add-on. It's best practice to provide localized assets for each language used in the regions you select.
  5. Review the information you have entered into the Publish panel. If it is all correct, click Publish.

Once you have completed these steps your add-on is fully configured for publishing. If you selected Private visibility for you add-on, the publication process completes in a few minutes, after which the add-on is available for install by your domain administrator or by users in your domain (if individual installs were enabled).

If you have selected Public visibility for your add-on, clicking the Publish button saves your configuration and starts a request for an add-on review. While your add-on is under review, the fields in the Publish panel of the SDK control panel cannot be changed.

Add-on review

When you complete the publication steps for a public add-on, a request for add-on review is automatically sent to the Google review team. A review team member then examines your add-on and its listing to ensure it is designed well, follows the add-on style guidelines, takes the appropriate steps to protect user data, and does not include any malicious code or unacceptable content.

After the review team member makes their initial assessment, you will receive an email communicating whether your add-on has been approved (and has been automatically added to the G Suite Marketplace) or if it requires additional work before it is publicly available.

If your add-on requires additional work, you will receive a review document containing specific information about what aspects of the add-on need improvement. Address all highlighted issues and follow the provided instructions to resumbit your add-on. Many developers are required to improve their add-ons prior to public release; some may be required to do this multiple times. You may always contact our review team for more information and guidance with this process. Once the review team's concerns are satisfied, you will be informed and your add-on will be automatically added the G Suite Marketplace.


Gmail Add-ons
Gmail Add-ons