Page Summary

outlined_flag

• 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 createwidgetsthat have linkedactions. You can usean action to compose new email drafts, optionally filling them usinginformation entered into the add-on UI or information from an open message.For example, you can have a button in youradd-on's message UIthat creates a reply to the currently opened message prepopulated withinformation from the add-on.

When an action that builds messages is triggered, Gmail executes a callbackfunction to build and return the draft. Gmail then displays that draft in itsUI in a standard email compose window, which the user can then edit and sendas needed.

Configuring an action to build a draft message

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

1. Make sure yourmanifestincludes theaction.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 ifthat scope is absolutely necessary.

2. Create anAction objectand associate it with acallback functionyou define.

3. Call the widget'ssetComposeAction()widget handler function,providing it theActionobject and specifying theComposeEmailType.

4. Implement the callback function that executes the draft-building action. Thisfunction is given anevent objectas an argument. The callback function must do the following:

   1. Create aGmailDraftobject.
   2. Build aComposeActionResponseobject using theComposeActionResponseBuilderclass and theGmailDraftobject.
   3. Return the builtComposeActionResponse.

You can prefill theGmailDraftyou create in the callback function withrecipients, a subject, a message body, and attachments. To fill in the draft,data can come from any source, but typically it derives from informationprovided to the add-on itself, information in the open message, orinformation gathered from a third-party service. Theevent objectpassed to the callback function contains the open message ID and other add-oninformation you can use to prefill the draft.

You can create the draft as a new standalone message or a reply toan existing message. This is controlled by theComposeEmailTypeenum given to thesetComposeAction().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 existingmessage. You can create a standalone draft with one of the followingGmail service functions:

• GmailApp.createDraft(recipient, subject, body)
• GmailApp.createDraft(recipient, subject, body, options)

Reply drafts

A reply draft is part of an existing message thread. Reply drafts are eithersingle 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 areply draft with one of theseGmail servicefunctions:

• GmailMessage.createDraftReply(body)
• GmailMessage.createDraftReply(body, options)
• GmailMessage.createDraftReplyAll(body)
• GmailMessage.createDraftReplyAll(body, options)
• GmailThread.createDraftReply(body)
• GmailThread.createDraftReply(body, options)
• GmailThread.createDraftReplyAll(body)
• GmailThread.createDraftReplyAll(body, options)

Example

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

varcomposeAction=CardService.newAction().setFunctionName('createReplyDraft');varcomposeButton=CardService.newTextButton().setText('Compose Reply').setComposeAction(composeAction,CardService.ComposedEmailType.REPLY_AS_DRAFT);//.../***Createsadraftemail(withanattachmentandinlineimage)*asareplytoanexistingmessage.*@param{Object}eAneventobjectpassedbytheaction.*@return{ComposeActionResponse}*/functioncreateReplyDraft(e){//ActivatetemporaryGmailscopes,inthiscasetoallow//areplytobedrafted.varaccessToken=e.gmail.accessToken;GmailApp.setCurrentMessageAccessToken(accessToken);//Createsadraftreply.varmessageId=e.gmail.messageId;varmessage=GmailApp.getMessageById(messageId);vardraft=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()}});//Returnabuiltdraftresponse.ThiscausesGmailtopresenta//composewindowtotheuser,pre-filledwiththecontentspecified//above.returnCardService.newComposeActionResponseBuilder().setGmailDraft(draft).build();}