技术问询：CardService.newGmailClientAction()返回的GmailClientAction用途及用法

Great question! I’ve stumbled upon this undocumented method while building Gmail add-ons too, so let me walk you through what it does and how to use it effectively.

What’s the Purpose of GmailClientAction? #

This is a hidden class in Google Apps Script’s CardService, designed specifically for Gmail add-ons. Its core job is to let you trigger native Gmail client actions directly from your add-on’s cards—no need to build custom UI or handle complex email interactions yourself. It bridges your add-on with Gmail’s built-in features, giving users a seamless, native-like experience.

How to Use It #

First, you’ll create a GmailClientAction instance with CardService.newGmailClientAction(), then configure it to trigger a specific Gmail action using the CardService.GmailAction enum. Here’s a practical example:

Example: Add a Button to Open the Current Email Thread #

function createGmailAddonCard() {
  // Create the Gmail client action to open the current thread
  const openThreadAction = CardService.newGmailClientAction()
    .setGmailAction(CardService.GmailAction.OPEN_THREAD);

  // Build a button that triggers this action
  const openButton = CardService.newTextButton()
    .setText("Open Full Email in Gmail")
    .setOnClickAction(openThreadAction);

  // Assemble the card
  const cardSection = CardService.newCardSection().addWidget(openButton);
  const card = CardService.newCardBuilder().addSection(cardSection).build();

  return [card];
}

Available Native Actions #

The CardService.GmailAction enum includes these supported actions:

• OPEN_THREAD: Opens the full email thread in Gmail’s native view
• REPLY: Launches the native reply window for the current email
• REPLY_ALL: Opens the reply-all window
• FORWARD: Triggers the native forward email interface

Important Notes #

• Undocumented API: Since this isn’t listed in Google’s official docs, Google could modify or remove it without warning. Use it cautiously in production add-ons, and have a fallback plan if it stops working.
• Gmail Add-Ons Only: This method only works within Gmail add-ons—you can’t use it in Sheets, Docs, or other Apps Script project types.
• Client Dependencies: Behavior might vary slightly across Gmail’s web, desktop, and mobile clients, so test your add-on in all environments if possible.

内容的提问来源于stack exchange，提问作者amsmota