Manifests

You develop your Gmail add-on using Apps Script. You define how you want your add-on to look and behave in an Apps Script project.

An Apps Script project manifest is a special JSON file that specifies a variety of details about the project, such as its library dependencies. For Gmail add-ons, the manifest also provides basic property information so that Gmail can correctly display and run the add-on.

Editing a manifest

The Apps Script editor hides manifest files by default in order to protect your Apps Script project settings. Follow these steps to make a hidden project manifest visible in the Apps Script editor:

  1. Open the script project in the Apps Script editor.
  2. Select View > Show project manifest.

The manifest file appears as another project file named appsscript.json. To hide the manifest file after you are finished, select View > Show project manifest again.

Manifest structure for Gmail add-ons

The following manifest file example snippet shows the section of a manifest file that defines a Gmail add-on. The gmail section of the manifest defines the name, logo URL, colors, and other settings for a Gmail add-on.

{
  ...
  "oauthScopes": [
    "https://www.googleapis.com/auth/gmail.addons.execute",
    "https://www.googleapis.com/auth/gmail.addons.current.message.metadata",
    "https://www.googleapis.com/auth/userinfo.email"
  ],
  "urlFetchWhitelist": [
    "https://www.example.com/myendpoint/"
  ],
  "gmail": {
    "name": "My Gmail Add-on",
    "logoUrl": "https://www.example.com/hosted/images/2x/my-icon.png",
    "primaryColor": "#4285F4",
    "secondaryColor": "#00BCD4",
    "authorizationCheckFunction": "get3PAuthorizationUrls",
    "contextualTriggers": [{
      "unconditional": {},
      "onTriggerFunction": "buildAddOn"
    }],
    "openLinkUrlPrefixes": [
      "https://mail.google.com/",
      "https://script.google.com/a/google.com/d/",
      "https://drive.google.com/a/google.com/file/d/",
      "https://en.wikipedia.org/wiki/",
      "https://www.example.com/",
    ],
    "universalActions": [{
      "text": "Open settings",
      "runFunction": "getSettingsCard"
     }, {
      "text": "Open help page",
      "openLink": "https://www.example.com/help"
    }],
    "version": "TRUSTED_TESTER_V2"
  }
}

The table below describes the manifest structure of fields under the gmail, oauthScopes, and urlFetchWhitelist sections. Gmail add-on manifests must have all the components marked as Required.

Property name Value Description
oauthScopes[] string Required. Defines the authorization scopes used by the add-on, some of which are required.
urlFetchWhitelist[] string Required if any URL is accessed via UrlFetch. A list of HTTPS URL prefixes. To protect user data, any URL endpoint fetched must match one of the prefixes in this list. This list must include any endpoint used in conjunction with authorizing third-party services. See Whitelisting URLs for more details.
gmail object Required. Defines values specific to Gmail add-ons.
gmail.authorizationCheckFunction string The name of an Apps Script function that performs third-party authorization requirement checks. This function is called before each invocation of the add-on. You can use it to ensure that the add-on is authorized to use each third-party service prior to any other add-on activity.
gmail.contextualTriggers[] list Defines a trigger that fires when the open email meets a specific criteria. When the trigger fires, it executes a specific Apps Script function, usually in order to create new cards and update the UI. Every add-on must define either a contextual trigger and/or a set of universal actions.
gmail.contextualTriggers[].onTriggerFunction string Required for each contextual trigger. The name of the Apps Script function that to executes when the trigger fires. See Code the add-on for details on how to define this function.
gmail.contextualTriggers[].unconditional object Required for each contextual trigger. Used to specify that the add-on is executed for all Gmail messages. This is currently the only option, so this should always be an empty object.
gmail.logoUrl string Required. The URL of the image shown in the toolbar.
gmail.name string Required. The name of the add-on shown in the toolbar.
gmail.openLinkUrlPrefixes[] list Required if the add-on displays any outbound links, whether within widgets using an OpenLink or text widget using HTML anchor tags. A list of HTTPS URL prefixes. To protect user data, any link rendered by the add-on must match one of the prefixes in this list. See Whitelisting URLs for more details.
gmail.primaryColor string The color of toolbar. Defaults to grey (#424242).
gmail.secondaryColor string The color of buttons and form elements. Defaults to the primary color (if it is set); otherwise defaults to blue (#2196F3).
gmail.universalActions[] list List of universal actions that are always available in the add-on UI. Every add-on must define either a contextual trigger, a set of universal actions, or both.
gmail.universalActions[].openLink string Required for each universal action if runFunction is not present. If provided, the URL that is opened in a tab when the user selects this action.
gmail.universalActions[].runFunction string Required for each universal action if openLink is not present. If provided, the name of the Apps Script function that executes when the user selects this action. See the Universal actions guide for details.
gmail.universalActions[].text string Required for each universal action. The text shown in the UI menu for this action.
gmail.version string Required. Must be set to "TRUSTED_TESTER_V2" to get the latest versions of Gmail add-on features.

Whitelisting URLs

Sometimes you may want your Gmail add-on to open a URL in response to a user action. Other times you may want your add-on to retrieve information from an external location using the Apps Script UrlFetch service. In both cases you must whitelist the URLs you open or fetch from in the project manifest. Whitelisting is the process where you designate specific URLs that are pre-approved for access by your add-on. This requirement helps protect user data; add-ons can't access URLs that have not been whitelisted.

You can whitelist a URL for opening by adding it or a matching prefix to the manifest gmail.openLinkUrlPrefixes field. Similarly, you can whitelist a URL for fetching by adding it or a matching prefix to the manifest urlFetchWhitelist field.

The prefixes you add to the manifest must satisfy the following requirements:

  • Each prefix must be a valid URL.
  • Each prefix must use https://, not http://.
  • Each prefix must have a full domain.
  • Each prefix must have a non-empty path. For example, https://www.google.com/ is valid but https://www.google.com is not.

When determining if a URL matches a whitelisted prefix, the following rules apply:

  • Path matching is case-sensitive.
  • If the prefix is identical to the URL, it is a match.
  • If the URL is the same or a child of the prefix, it is a match.

For example, the prefix https://example.com/foo matches the following URLs:

  • https://example.com/foo
  • https://example.com/foo/
  • https://example.com/foo/bar
  • https://example.com/foo?bar
  • https://example.com/foo#bar