Advanced Gmail Service

  • The Advanced Gmail service allows using the Gmail API in Apps Script to find and modify threads, messages, and labels.

  • While the built-in Gmail service is often simpler, the advanced service offers extra features and more detailed information.

  • This is an advanced service that requires enabling before use.

  • Reference documentation for the Gmail API is available for detailed information on this service.

  • To improve performance,list requests often return limited information, requiring a follow-upget request for full details.

The Advanced Gmail service allows you to use theGmail API inApps Script. Much like Apps Script'sbuilt-in Gmail service,this API allows scripts to find and modify threads, messages, and labels in aGmail mailbox. In most cases, the built-in service is easier to use, but thisadvanced service provides a few extra features and access to more detailedinformation about Gmail content.

Note: This is an advanced service that must beenabled before use.

Reference

For detailed information on this service, see thereference documentation for the Gmail API.Like all advanced services in Apps Script, the advanced Gmail service uses thesame objects, methods, and parameters as the public API. For more information, seeHow method signatures are determined.

Note: To improve performance, the Gmail API often restricts the amount ofinformation returned fromlist requests to thread, message or label IDs andother simple information. More detailed information about a particular thread,message or label can be obtained by issuing a follow-upget request using theassociated ID.

To report issues and find other support, see theGmail support guide.

Sample code

The sample code below usesversion 1 of the API.

List label information

The following example demonstrates how to list all the user's label information.This includes the label name, type, ID and visibility settings.

advanced/gmail.gs
/** * Lists the user's labels, including name, type, * ID and visibility information. */functionlistLabelInfo(){try{constresponse=Gmail.Users.Labels.list("me");for(leti=0;i <response.labels.length;i++){constlabel=response.labels[i];console.log(JSON.stringify(label));}}catch(err){console.log(err);}}

List inbox snippets

The following example demonstrates how to list text snippets associated witheach thread in the user's Inbox. Notice the use of page tokens to access thefull list of results.

advanced/gmail.gs
/** * Lists, for each thread in the user's Inbox, a * snippet associated with that thread. */functionlistInboxSnippets(){try{letpageToken;do{constthreadList=Gmail.Users.Threads.list("me",{q:"label:inbox",pageToken:pageToken,});if(threadList.threads &&threadList.threads.length >0){for(constthreadofthreadList.threads){console.log(`Snippet:${thread.snippet}`);}}pageToken=threadList.nextPageToken;}while(pageToken);}catch(err){console.log(err);}}

List recent history

The following example demonstrates how to log recent activity history.Specifically, this example recovers the history record ID associated with theuser's most recently sent message, and then logs the message IDs of everymessage that has changed since that time. Each changed message is only loggedonce, no matter how many change events are in the history records. Notice theuse of page tokens to access the full list of results.

advanced/gmail.gs
/** * Gets a history record ID associated with the most * recently sent message, then logs all the message IDs * that have changed since that message was sent. */functionlogRecentHistory(){try{// Get the history ID associated with the most recent// sent message.constsent=Gmail.Users.Threads.list("me",{q:"label:sent",maxResults:1,});if(!sent.threads||!sent.threads[0]){console.log("No sent threads found.");return;}consthistoryId=sent.threads[0].historyId;// Log the ID of each message changed since the most// recent message was sent.letpageToken;constchanged=[];do{constrecordList=Gmail.Users.History.list("me",{startHistoryId:historyId,pageToken:pageToken,});consthistory=recordList.history;if(history &&history.length >0){for(constrecordofhistory){for(constmessageofrecord.messages){if(changed.indexOf(message.id)===-1){changed.push(message.id);}}}}pageToken=recordList.nextPageToken;}while(pageToken);for(constidofchanged){console.log("Message Changed: %s",id);}}catch(err){console.log(err);}}

List messages

The following example demonstrates how to list the Gmail user'sunread messages.

advanced/gmail.gs
/** * Lists unread messages in the user's inbox using the advanced Gmail service. */functionlistMessages(){// The special value 'me' indicates the authenticated user.constuserId="me";// Define optional parameters for the request.constoptions={maxResults:10,// Limit the number of messages returned.q:"is:unread",// Search for unread messages.};try{// Call the Gmail.Users.Messages.list method.constresponse=Gmail.Users.Messages.list(userId,options);constmessages=response.messages;console.log("Unread Messages:");for(constmessageofmessages){console.log(`- Message ID:${message.id}`);}}catch(err){// Log any errors to the Apps Script execution log.console.log(`Failed with error:${err.message}`);}}

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-11 UTC.