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 or Team Drive. 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.

Before you begin publication, be sure to review and configure your project collaborator access settings.

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).
  • Style. Follow the recommendations in the add-on style guide.
  • Collaborators. If you are collaborating with others to build and maintain this add-on, be sure to configure your project collaborator access settings.

Technical requirements

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

  • Standard Cloud Platform (GCP) project. The add-on must use a standard GCP project. If the add-on is using a default GCP project, switch to a standard GCP project. All collaborators working on the add-on should have access to the standard GCP project.
  • 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 contextual 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.

  • 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.
  • File access changes. If your add-on needs to update the access control list (ACL) of a G Suite or third-party file, it must inform the user it is doing so. ACL changes can't be handled silently in the background. For example, an add-on can't silently add email recipients to the set of accounts that can view a Dropbox file. Instead, the add-on should inform the user about the ACL change the add-on wishes to make and ask the user to confirm the change. Add-ons that don't inform users of such changes can't pass add-on review.

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 configuring the add-on's OAuth consent screen using the assets you collected. Some of the form elements are optional, but providing them can improve your add-on's user experience.

Step 3: Request review for public add-ons

All add-ons that are published publicly must undergo an add-on review. In addition, a Gmail add-on must complete this review before you can configure its G Suite Marketplace store listing.

If you are publishing your add-on privately, skip to Step 4. If you want to publish your add-on publicly, follow these steps:

  1. Fill out this review request form using the assets you assembled. This starts the add-on review process.

    Once the review process is complete and you have received the review team's approval, they whitelist your add-on for publication. This allows you to select Public visibility for the add-on when you configure its G Suite Marketplace store listing.

  2. Request OAuth verification for your add-on script project. This requires that you show ownership of a domain and that you have a privacy policy hosted within that domain. The verification process can take up to 72 hours to complete. Be sure request verification only after the add-on review process is finished, as otherwise you may be required to repeat the verification procedure.

Step 4: Enable the Marketplace SDK

The G Suite Marketplace SDK lets you configure the appearance of your G Suite Marketplace listing. Be sure to enable the "G Suite Marketplace SDK" in your add-on script project.

You may be prompted during this process to accept the Google APIs Terms of Service and the G Suite Marketplace SDK Terms of Service. Read the terms carefully, then check the box and click Accept to continue the publishing procedure.

Once you have enabled the G Suite Marketplace SDK for your script project, you can use the SDK control panel to configure the SDK.

Step 5: 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 you 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. 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).

Add-on review

You must explicitly request add-on review of public Gmail add-ons prior to configuring the G Suite Marketplace SDK. After your add-on is approved, you must complete the remainder of the publication process.

For more details, see Add-on review.