Triggers for Gmail add-ons

Apps Script triggers cause a specified script function (the trigger function) to execute whenever a specified event occurs. Only certain events can cause triggers to fire, and each G Suite application supports a different set of events.

When a trigger fires, an event object is created. This JSON structure contains details about the event that occurred. The information in the event object structure is organized differently based on the trigger type.

Once the event object is created, Apps Script passes it as a parameter to the trigger function. The trigger function is a callback function that you must implement yourself, to take whatever actions are appropriate to respond to the event. For example, in a Gmail add-on a trigger is used to create a new card interface when the user opens a message thread. In this case, you implement a contextual trigger function to create the cards making up the new UI using the data passed in the event object.

This page provides guidelines on using triggers in Gmail add-on projects.

Manifest triggers

Unlike editor add-ons, Gmail add-ons currently can't use generic Apps Script simple triggers or installable triggers. Instead, they use triggers designed specifically for Gmail add-ons: manifest triggers.

Manifest triggers are defined completely in the Gmail add-on's manifest. Unlike installable triggers, you can't use the Apps Script Script service to define them programmatically.

There are two kinds of triggers that Gmail add-ons can define in their manifest: contextual triggers and a compose triggers:

  • Contextual triggers fire when messages that meet the trigger criteria are opened in Gmail while the add-on is also open. Contextual triggers are used to control what part of the add-on interface to displayed as the result of the message and its content. When fired, contextual triggers are passed an action event object.

  • Compose triggers are essentially callbacks. They fire when the user attempts to open the add-on from the Gmail compose window, and control what the add-on first displays. When fired, compose triggers are passed a compose trigger event object.

For more information about these trigger types, see Extending the message UI and Extending the compose UI.

Restrictions

Contextual and compose triggers have certain restrictions to their use.

  • These triggers are only used in Gmail add-on projects; they have no purpose in any other application.
  • Since they are defined in the add-on manifest and not in its code, you can't use the Apps Script Script service to create or modify these triggers.
  • Contextual triggers currently can only have an unconditional criteria. This means contextual triggers fire for every email message, regardless of content.