Composing draft messages

AI-generated Key Takeaways

This guide explains how to use Google Workspace add-ons to create new email drafts prefilled with information from the add-on or the currently open message.
Add-ons achieve this functionality by using actions associated with widgets like buttons, triggering callback functions to build and return drafts.
To implement this, you need to include a specific scope in your manifest, create an action object with a callback function, and configure the widget to trigger the action.
The callback function creates a GmailDraft object, builds a ComposeActionResponse, and can prefill the draft with data from various sources.
Drafts can be created as standalone messages or replies (single or reply-all) using corresponding Gmail service functions.

In a Google Workspace add-on you can create widgets that have linked actions . You can use an action to compose new email drafts, optionally filling them using information entered into the add-on UI or information from an open message. For example, you can have a button in your add-on's message UI that creates a reply to the currently opened message prepopulated with information from the add-on.

When an action that builds messages is triggered, Gmail executes a callback function to build and return the draft. Gmail then displays that draft in its UI in a standard email compose window, which the user can then edit and send as needed.

Configuring an action to build a draft message

To configure a widget to start a draft-building action when selected, you must do the following:

Make sure your manifest includes the action.compose scope :

https://www.googleapis.com/auth/gmail.addons.current.action.compose

You can use more a permissive scope instead, but should only do so if that scope is absolutely necessary.
Create an Action object and associate it with a callback function you define.
Call the widget's setComposeAction() widget handler function , providing it the Action object and specifying the ComposeEmailType .
Implement the callback function that executes the draft-building action. This function is given an event object as an argument. The callback function must do the following:
1. Create a GmailDraft object.
2. Build a ComposeActionResponse object using the ComposeActionResponseBuilder class and the GmailDraft object.
3. Return the built ComposeActionResponse .

You can prefill the GmailDraft you create in the callback function with recipients, a subject, a message body, and attachments. To fill in the draft, data can come from any source, but typically it derives from information provided to the add-on itself, information in the open message, or information gathered from a third-party service. The event object passed to the callback function contains the open message ID and other add-on information you can use to prefill the draft.

You can create the draft as a new standalone message or a reply to an existing message. This is controlled by the ComposeEmailType enum given to the setComposeAction() . You can create reply drafts as single replies or 'reply-all' messages.

Standalone drafts

A standalone draft starts a new thread and isn't a reply to any existing message. You can create a standalone draft with one of the following Gmail service functions:

Reply drafts

A reply draft is part of an existing message thread. Reply drafts are either single replies that only get sent to the sender of a message or "reply all" drafts that get sent to everyone who received that message. You can create a reply draft with one of these Gmail service functions:

Example

The following code snippet shows how to assign an action that builds a reply draft to a button.

   
 var 
  
 composeAction 
  
 = 
  
 CardService 
 . 
 newAction 
 () 
  
 . 
 setFunctionName 
 ( 
 'createReplyDraft' 
 ); 
  
 var 
  
 composeButton 
  
 = 
  
 CardService 
 . 
 newTextButton 
 () 
  
 . 
 setText 
 ( 
 'Compose Reply' 
 ) 
  
 . 
 setComposeAction 
 ( 
  
 composeAction 
 , 
  
 CardService 
 . 
 ComposedEmailType 
 . 
 REPLY_AS_DRAFT 
 ); 
  
 // 
  
 ... 
  
 /** 
  
 * 
  
 Creates 
  
 a 
  
 draft 
  
 email 
  
 ( 
 with 
  
 an 
  
 attachment 
  
 and 
  
 inline 
  
 image 
 ) 
  
 * 
  
 as 
  
 a 
  
 reply 
  
 to 
  
 an 
  
 existing 
  
 message 
 . 
  
 * 
  
 @ 
 param 
  
 { 
 Object 
 } 
  
 e 
  
 An 
  
 event 
  
 object 
  
 passed 
  
 by 
  
 the 
  
 action 
 . 
  
 * 
  
 @ 
 return 
  
 { 
 ComposeActionResponse 
 } 
  
 */ 
  
 function 
  
 createReplyDraft 
 ( 
 e 
 ) 
  
 { 
  
 // 
  
 Activate 
  
 temporary 
  
 Gmail 
  
 scopes 
 , 
  
 in 
  
 this 
  
 case 
  
 to 
  
 allow 
  
 // 
  
 a 
  
 reply 
  
 to 
  
 be 
  
 drafted 
 . 
  
 var 
  
 accessToken 
  
 = 
  
 e 
 . 
 gmail 
 . 
 accessToken 
 ; 
  
 GmailApp 
 . 
 setCurrentMessageAccessToken 
 ( 
 accessToken 
 ); 
  
 // 
  
 Creates 
  
 a 
  
 draft 
  
 reply 
 . 
  
 var 
  
 messageId 
  
 = 
  
 e 
 . 
 gmail 
 . 
 messageId 
 ; 
  
 var 
  
 message 
  
 = 
  
 GmailApp 
 . 
 getMessageById 
 ( 
 messageId 
 ); 
  
 var 
  
 draft 
  
 = 
  
 message 
 . 
 createDraftReply 
 ( 
 '' 
 , 
  
 { 
  
 htmlBody 
 : 
  
 "Kitten! <img src='cid:kitten'/>" 
 , 
  
 attachments 
 : 
  
 [ 
  
 UrlFetchApp 
 . 
 fetch 
 ( 
 'https://example.com/images/myDog.jpg' 
 ) 
  
 . 
 getBlob 
 () 
  
 ], 
  
 inlineImages 
 : 
  
 { 
  
 "kitten" 
 : 
  
 UrlFetchApp 
 . 
 fetch 
 ( 
 'https://example.com/images/myKitten.jpg' 
 ) 
  
 . 
 getBlob 
 () 
  
 } 
  
 } 
  
 ); 
  
 // 
  
 Return 
  
 a 
  
 built 
  
 draft 
  
 response 
 . 
  
 This 
  
 causes 
  
 Gmail 
  
 to 
  
 present 
  
 a 
  
 // 
  
 compose 
  
 window 
  
 to 
  
 the 
  
 user 
 , 
  
 pre 
 - 
 filled 
  
 with 
  
 the 
  
 content 
  
 specified 
  
 // 
  
 above 
 . 
  
 return 
  
 CardService 
 . 
 newComposeActionResponseBuilder 
 () 
  
 . 
 setGmailDraft 
 ( 
 draft 
 ) 
 . 
 build 
 (); 
  
 }