Class GmailApp

GmailApp

Provides access to Gmail threads, messages, and labels.

Methods

Method	Return type	Brief description
`createDraft(recipient, subject, body)`	`GmailDraft`	Creates a draft email message.
`createDraft(recipient, subject, body, options)`	`GmailDraft`	Creates a draft email message with optional arguments.
`createLabel(name)`	`GmailLabel`	Create a new user label of the given name.
`deleteLabel(label)`	`GmailApp`	Deletes the specified label.
`getAliases()`	`String[]`	Gets a list of the emails that are set up as aliases for this account in Gmail.
`getDraft(draftId)`	`GmailDraft`	Retrieve an email message draft by ID.
`getDraftMessages()`	`GmailMessage[]`	Retrieves all draft messages.
`getDrafts()`	`GmailDraft[]`	Gets all Gmail draft messages.
`getInboxThreads()`	`GmailThread[]`	Retrieves all Inbox threads irrespective of labels.
`getInboxThreads(start, max)`	`GmailThread[]`	Retrieves a range of Inbox threads irrespective of labels.
`getInboxUnreadCount()`	`Integer`	Gets the number of unread threads in the inbox.
`getMessageById(id)`	`GmailMessage`	Gets a message by ID.
`getMessagesForThread(thread)`	`GmailMessage[]`	Retrieve all messages in the specified thread.
`getMessagesForThreads(threads)`	`GmailMessage[][]`	Retrieve all messages in the specified threads.
`getPriorityInboxThreads()`	`GmailThread[]`	Retrieves all Priority Inbox threads irrespective of labels.
`getPriorityInboxThreads(start, max)`	`GmailThread[]`	Retrieves a range of Priority Inbox threads irrespective of labels.
`getPriorityInboxUnreadCount()`	`Integer`	Gets the number of unread threads in the Priority Inbox.
`getSpamThreads()`	`GmailThread[]`	Retrieves all spam threads irrespective of labels.
`getSpamThreads(start, max)`	`GmailThread[]`	Retrieves a range of spam threads irrespective of labels.
`getSpamUnreadCount()`	`Integer`	Gets the number of unread threads that are spam.
`getStarredThreads()`	`GmailThread[]`	Retrieves all starred threads irrespective of labels.
`getStarredThreads(start, max)`	`GmailThread[]`	Retrieves a range of starred threads irrespective of labels.
`getStarredUnreadCount()`	`Integer`	Gets the number of unread threads that are starred.
`getThreadById(id)`	`GmailThread`	Gets a thread by ID.
`getTrashThreads()`	`GmailThread[]`	Retrieves all trash threads irrespective of labels.
`getTrashThreads(start, max)`	`GmailThread[]`	Retrieves a range of trash threads irrespective of labels.
`getUserLabelByName(name)`	`GmailLabel`	Retrieves a label given the label name.
`getUserLabels()`	`GmailLabel[]`	Retrieves a list of user-created labels.
`markMessageRead(message)`	`GmailApp`	Marks this message read and forces the message to refresh.
`markMessageUnread(message)`	`GmailApp`	Marks this message unread and forces the message to refresh.
`markMessagesRead(messages)`	`GmailApp`	Marks these messages read and forces the messages to refresh.
`markMessagesUnread(messages)`	`GmailApp`	Marks these messages unread and forces the messages to refresh.
`markThreadImportant(thread)`	`GmailApp`	Marks this thread as important and forces the thread to refresh.
`markThreadRead(thread)`	`GmailApp`	Marks this thread as read and forces the thread to refresh.
`markThreadUnimportant(thread)`	`GmailApp`	Marks this thread as unimportant and forces the thread to refresh.
`markThreadUnread(thread)`	`GmailApp`	Marks this thread unread and forces the thread to refresh.
`markThreadsImportant(threads)`	`GmailApp`	Marks these threads as important and forces the threads to refresh.
`markThreadsRead(threads)`	`GmailApp`	Marks these threads as read and forces the threads to refresh.
`markThreadsUnimportant(threads)`	`GmailApp`	Marks these threads as unimportant and forces the threads to refresh.
`markThreadsUnread(threads)`	`GmailApp`	Marks these threads as unread and forces the threads to refresh.
`moveMessageToTrash(message)`	`GmailApp`	Moves the message to the trash and forces the message to refresh.
`moveMessagesToTrash(messages)`	`GmailApp`	Moves the specified messages to the trash and forces the messages to refresh.
`moveThreadToArchive(thread)`	`GmailApp`	Moves this thread to the archive and forces the thread to refresh.
`moveThreadToInbox(thread)`	`GmailApp`	Moves this thread to the inbox and forces the thread to refresh.
`moveThreadToSpam(thread)`	`GmailApp`	Moves this thread to spam and forces the thread to refresh.
`moveThreadToTrash(thread)`	`GmailApp`	Moves this thread to the trash and forces the thread to refresh.
`moveThreadsToArchive(threads)`	`GmailApp`	Moves these threads to the archive and forces the threads to refresh.
`moveThreadsToInbox(threads)`	`GmailApp`	Moves these threads to the inbox and forces the threads to refresh.
`moveThreadsToSpam(threads)`	`GmailApp`	Moves these threads to spam and forces the threads to refresh.
`moveThreadsToTrash(threads)`	`GmailApp`	Moves these threads to the trash and forces the threads to refresh.
`refreshMessage(message)`	`GmailApp`	Reloads the message and associated state from Gmail (useful in case the labels, read state, etc., have changed).
`refreshMessages(messages)`	`GmailApp`	Reloads the messages and associated state from Gmail (useful in case the labels, read state, etc., have changed).
`refreshThread(thread)`	`GmailApp`	Reloads the thread and associated state from Gmail (useful in case the labels, read state, etc., have changed).
`refreshThreads(threads)`	`GmailApp`	Reloads the threads and associated state from Gmail (useful in case the labels, read state, etc., have changed).
`search(query)`	`GmailThread[]`	Search Gmail with the given query.
`search(query, start, max)`	`GmailThread[]`	Search Gmail with the given query.
`sendEmail(recipient, subject, body)`	`GmailApp`	Sends an email message.
`sendEmail(recipient, subject, body, options)`	`GmailApp`	Sends an email message with optional arguments.
`setCurrentMessageAccessToken(accessToken)`	`void`	Sets the current message access token that enables the script to access the current `GmailMessage` properties.
`starMessage(message)`	`GmailApp`	Adds a star to this message and forces the message to refresh.
`starMessages(messages)`	`GmailApp`	Adds stars to these messages and forces the messages to refresh.
`unstarMessage(message)`	`GmailApp`	Removes a star from this message and forces the message to refresh.
`unstarMessages(messages)`	`GmailApp`	Removes stars from these messages and forces the messages to refresh.

Deprecated methods

Method	Return type	Brief description
~~`getChatThreads()`~~	`GmailThread[]`	Gets all classic Google Hangouts threads and Google Chat threads until Google switches all users of classic Hangouts to Chat later this year.
~~`getChatThreads(start, max)`~~	`GmailThread[]`	Gets a range of classic Google Hangouts threads and Google Chat threads until Google switches all users of classic Hangouts to Chat later this year.

Detailed documentation

`createDraft(recipient, subject, body)`

Creates a draft email message. The size of the email (including headers) is quota limited .

 // 
  
 The 
  
 code 
  
 below 
  
 creates 
  
 a 
  
 draft 
  
 email 
  
 with 
  
 the 
  
 current 
  
 date 
  
 and 
  
 time 
 . 
 var 
  
 now 
  
 = 
  
 new 
  
 Date 
 (); 
 GmailApp 
 . 
 createDraft 
 ( 
 "mike@example.com" 
 , 
  
 "current time" 
 , 
  
 "The time is: " 
  
 + 
  
 now 
 . 
 toString 
 ());

Parameters

Name	Type	Description
`recipient`	`String`	comma separated list of email addresses
`subject`	`String`	subject of the email
`body`	`String`	body of the email

Return

GmailDraft — the newly created GmailDraft

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`createDraft(recipient, subject, body, options)`

Creates a draft email message with optional arguments. The email can contain plain text or an HTML body. The size of the email (including headers, but excluding attachments) is quota limited .

 // 
  
 Create 
  
 a 
  
 draft 
  
 email 
  
 with 
  
 a 
  
 file 
  
 from 
  
 Google 
  
 Drive 
  
 attached 
  
 as 
  
 a 
  
 PDF 
 . 
 var 
  
 file 
  
 = 
  
 DriveApp 
 . 
 getFileById 
 ( 
 '1234567890abcdefghijklmnopqrstuvwxyz' 
 ); 
 GmailApp 
 . 
 createDraft 
 ( 
 'mike@example.com' 
 , 
  
 'Attachment example' 
 , 
  
 'Please see attached file.' 
 , 
  
 { 
  
 attachments 
 : 
  
 [ 
 file 
 . 
 getAs 
 ( 
 MimeType 
 . 
 PDF 
 )], 
  
 name 
 : 
  
 'Automatic Emailer Script' 
 });

Parameters

Name	Type	Description
`recipient`	`String`	the addresses of the recipient
`subject`	`String`	the subject line
`body`	`String`	the body of the email
`options`	`Object`	a JavaScript object that specifies advanced parameters, as listed below

Advanced parameters

Name	Type	Description
`attachments`	`BlobSource[]`	an array of files to send with the email
`bcc`	`String`	a comma-separated list of email addresses to BCC
`cc`	`String`	a comma-separated list of email addresses to CC
`from`	`String`	the address that the email should be sent from, which must be one of the values returned by `getAliases()`
`htmlBody`	`String`	if set, devices capable of rendering HTML will use it instead of the required body argument; you can add an optional `inlineImages` field in HTML body if you have inlined images for your email
`inlineImages`	`Object`	a JavaScript object containing a mapping from image key ( `String` ) to image data ( `BlobSource` ); this assumes that the `htmlBody` parameter is used and contains references to these images in the format `<img src="cid:imageKey" />`
`name`	`String`	the name of the sender of the email (default: the user's name)
`replyTo`	`String`	an email address to use as the default reply-to address (default: the user's email address)

Return

GmailDraft — the newly created GmailDraft

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`createLabel(name)`

Create a new user label of the given name.

 // Creates the label @FOO and logs label: FOO 
 Logger 
 . 
 log 
 ( 
 "label: " 
  
 + 
  
 GmailApp 
 . 
 createLabel 
 ( 
 "FOO" 
 ));

Parameters

Name	Type	Description
`name`	`String`	the name of the new label

Return

GmailLabel — the newly created label

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`deleteLabel(label)`

Deletes the specified label.

 // 
  
 Have 
  
 to 
  
 get 
  
 the 
  
 label 
  
 by 
  
 name 
  
 first 
 var 
  
 label 
  
 = 
  
 GmailApp 
 . 
 getUserLabelByName 
 ( 
 "FOO" 
 ); 
 GmailApp 
 . 
 deleteLabel 
 ( 
 label 
 );

Parameters

Name	Type	Description
`label`	`GmailLabel`	the label to delete

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`getAliases()`

Gets a list of the emails that are set up as aliases for this account in Gmail.

You can send a message from any of these aliases by using the "from" optional argument.

 // 
  
 Log 
  
 the 
  
 aliases 
  
 for 
  
 this 
  
 Gmail 
  
 account 
  
 and 
  
 send 
  
 an 
  
 email 
  
 as 
  
 the 
  
 first 
  
 one 
 . 
 var 
  
 me 
  
 = 
  
 Session 
 . 
 getActiveUser 
 () 
 . 
 getEmail 
 (); 
 var 
  
 aliases 
  
 = 
  
 GmailApp 
 . 
 getAliases 
 (); 
 Logger 
 . 
 log 
 ( 
 aliases 
 ); 
 if 
  
 ( 
 aliases 
 . 
 length 
 > 
 0 
 ) 
  
 { 
  
 GmailApp 
 . 
 sendEmail 
 ( 
 me 
 , 
  
 'From an alias' 
 , 
  
 'A message from an alias!' 
 , 
  
 { 
 'from' 
 : 
  
 aliases 
 [ 
 0 
 ]}); 
 } 
  
 else 
  
 { 
  
 GmailApp 
 . 
 sendEmail 
 ( 
 me 
 , 
  
 'No aliases found' 
 , 
  
 'You have no aliases.' 
 ); 
 }

Return

String[] — an array of aliases for this account

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`getDraft(draftId)`

Retrieve an email message draft by ID.

Use this in conjunction with getId() on Gmail drafts.

 // 
  
 Get 
  
 the 
  
 first 
  
 draft 
  
 message 
  
 in 
  
 your 
  
 drafts 
  
 folder 
 var 
  
 draft 
  
 = 
  
 GmailApp 
 . 
 getDrafts 
 ()[ 
 0 
 ]; 
 // 
  
 Get 
  
 its 
  
 ID 
 var 
  
 draftId 
  
 = 
  
 draft 
 . 
 getId 
 (); 
 // 
  
 Now 
  
 fetch 
  
 the 
  
 same 
  
 draft 
  
 using 
  
 that 
  
 ID 
 . 
 var 
  
 draftById 
  
 = 
  
 GmailApp 
 . 
 getDraft 
 ( 
 draftId 
 ); 
 // 
  
 Should 
  
 always 
  
 log 
  
 true 
  
 as 
  
 they 
  
 should 
  
 be 
  
 the 
  
 same 
  
 message 
 Logger 
 . 
 log 
 ( 
 draft 
 . 
 getMessage 
 () 
 . 
 getSubject 
 () 
  
 == 
  
 draftById 
 . 
 getMessage 
 () 
 . 
 getSubject 
 ());

Parameters

Name	Type	Description
`draftId`	`String`	the ID of the draft to retrieve

Return

GmailDraft — the draft with the given ID

Throws

Error — if no draft with the given ID can be found

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`getDraftMessages()`

Retrieves all draft messages.

 // 
  
 Logs 
  
 the 
  
 number 
  
 of 
  
 draft 
  
 messages 
 var 
  
 drafts 
  
 = 
  
 GmailApp 
 . 
 getDraftMessages 
 (); 
 Logger 
 . 
 log 
 ( 
 drafts 
 . 
 length 
 );

Return

GmailMessage[] — an array of draft Gmail messages

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`getDrafts()`

Gets all Gmail draft messages.

 var 
  
 drafts 
  
 = 
  
 GmailApp 
 . 
 getDrafts 
 (); 
 for 
  
 ( 
 var 
  
 i 
  
 = 
  
 0 
 ; 
  
 i 
 < 
 drafts 
 . 
 length 
 ; 
  
 i 
 ++ 
 ) 
  
 { 
  
 Logger 
 . 
 log 
 ( 
 drafts 
 [ 
 i 
 ] 
 . 
 getId 
 ()); 
 }

Return

GmailDraft[] — an array of Gmail draft messages

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`getInboxThreads()`

Retrieves all Inbox threads irrespective of labels.

This call will fail when the size of all threads is too large for the system to handle. Where the thread size is unknown, and potentially very large, please use the 'paged' call, and specify ranges of the threads to retrieve in each call.

 // 
  
 Log 
  
 the 
  
 subject 
  
 lines 
  
 of 
  
 your 
  
 Inbox 
 var 
  
 threads 
  
 = 
  
 GmailApp 
 . 
 getInboxThreads 
 (); 
 for 
  
 ( 
 var 
  
 i 
  
 = 
  
 0 
 ; 
  
 i 
 < 
 threads 
 . 
 length 
 ; 
  
 i 
 ++ 
 ) 
  
 { 
  
 Logger 
 . 
 log 
 ( 
 threads 
 [ 
 i 
 ] 
 . 
 getFirstMessageSubject 
 ()); 
 }

Return

GmailThread[] — an array of Gmail threads in the Inbox

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`getInboxThreads(start, max)`

Retrieves a range of Inbox threads irrespective of labels.

 // 
  
 Log 
  
 the 
  
 subject 
  
 lines 
  
 of 
  
 up 
  
 to 
  
 the 
  
 first 
  
 50 
  
 emails 
  
 in 
  
 your 
  
 Inbox 
 var 
  
 threads 
  
 = 
  
 GmailApp 
 . 
 getInboxThreads 
 ( 
 0 
 , 
  
 50 
 ); 
 for 
  
 ( 
 var 
  
 i 
  
 = 
  
 0 
 ; 
  
 i 
 < 
 threads 
 . 
 length 
 ; 
  
 i 
 ++ 
 ) 
  
 { 
  
 Logger 
 . 
 log 
 ( 
 threads 
 [ 
 i 
 ] 
 . 
 getFirstMessageSubject 
 ()); 
 }

Parameters

Name	Type	Description
`start`	`Integer`	the index of the first thread to retrieve
`max`	`Integer`	the maximum number of threads to retrieve

Return

GmailThread[] — an array of Gmail threads in the Inbox

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`getInboxUnreadCount()`

Gets the number of unread threads in the inbox.

 Logger 
 . 
 log 
 ( 
 "Messages unread in inbox: " 
  
 + 
  
 GmailApp 
 . 
 getInboxUnreadCount 
 ());

Return

Integer — the number of threads in the inbox that have unread messages

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`getMessageById(id)`

Gets a message by ID.

Use this in conjunction with getId() on Gmail messages.

 // 
  
 Get 
  
 the 
  
 first 
  
 message 
  
 in 
  
 the 
  
 first 
  
 thread 
  
 of 
  
 your 
  
 inbox 
 var 
  
 message 
  
 = 
  
 GmailApp 
 . 
 getInboxThreads 
 ( 
 0 
 , 
  
 1 
 )[ 
 0 
 ] 
 . 
 getMessages 
 ()[ 
 0 
 ]; 
 // 
  
 Get 
  
 its 
  
 ID 
 var 
  
 messageId 
  
 = 
  
 message 
 . 
 getId 
 (); 
 // 
  
 Now 
  
 fetch 
  
 the 
  
 same 
  
 message 
  
 using 
  
 that 
  
 ID 
 . 
 var 
  
 messageById 
  
 = 
  
 GmailApp 
 . 
 getMessageById 
 ( 
 messageId 
 ); 
 // 
  
 Should 
  
 always 
  
 log 
  
 true 
  
 as 
  
 they 
  
 should 
  
 be 
  
 the 
  
 same 
  
 message 
 Logger 
 . 
 log 
 ( 
 message 
 . 
 getSubject 
 () 
  
 == 
  
 messageById 
 . 
 getSubject 
 ());

Parameters

Name	Type	Description
`id`	`String`	the ID of the message to retrieve

Return

GmailMessage — the message with the given ID

Throws

Error — if no message with the given ID can be found

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`getMessagesForThread(thread)`

Retrieve all messages in the specified thread.

 // 
  
 Log 
  
 all 
  
 the 
  
 subject 
  
 lines 
  
 in 
  
 the 
  
 first 
  
 thread 
  
 of 
  
 your 
  
 inbox 
 var 
  
 thread 
  
 = 
  
 GmailApp 
 . 
 getInboxThreads 
 ( 
 0 
 , 
  
 1 
 ) 
 [ 
 0 
 ] 
 ; 
 var 
  
 messages 
  
 = 
  
 GmailApp 
 . 
 getMessagesForThread 
 ( 
 thread 
 ); 
 for 
  
 ( 
 var 
  
 i 
  
 = 
  
 0 
  
 ; 
  
 i 
 < 
 messages 
 . 
 length 
 ; 
  
 i 
 ++ 
 ) 
  
 { 
  
 Logger 
 . 
 log 
 ( 
 "subject: " 
  
 + 
  
 messages 
 [ 
 i 
 ] 
 . 
 getSubject 
 ()); 
 }

Parameters

Name	Type	Description
`thread`	`GmailThread`	the thread of messages to retrieve

Return

GmailMessage[] — array of messages corresponding to this thread

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`getMessagesForThreads(threads)`

Retrieve all messages in the specified threads.

 // 
  
 Log 
  
 the 
  
 subject 
  
 lines 
  
 of 
  
 all 
  
 messages 
  
 in 
  
 the 
  
 first 
  
 two 
  
 threads 
  
 of 
  
 your 
  
 inbox 
 var 
  
 thread 
  
 = 
  
 GmailApp 
 . 
 getInboxThreads 
 ( 
 0 
 , 
  
 2 
 ); 
 var 
  
 messages 
  
 = 
  
 GmailApp 
 . 
 getMessagesForThreads 
 ( 
 thread 
 ); 
 for 
  
 ( 
 var 
  
 i 
  
 = 
  
 0 
  
 ; 
  
 i 
 < 
 messages 
 . 
 length 
 ; 
  
 i 
 ++ 
 ) 
  
 { 
  
 for 
  
 ( 
 var 
  
 j 
  
 = 
  
 0 
 ; 
  
 j 
 < 
 messages 
 [ 
 i 
 ] 
 . 
 length 
 ; 
  
 j 
 ++ 
 ) 
  
 { 
  
 Logger 
 . 
 log 
 ( 
 "subject: " 
  
 + 
  
 messages 
 [ 
 i 
 ][ 
 j 
 ] 
 . 
 getSubject 
 ()); 
  
 } 
 }

Parameters

Name	Type	Description
`threads`	`GmailThread[]`	the threads of messages to retrieve

Return

GmailMessage[][] — an array of arrays of messages, where each item in the outer array corresponds to a thread and the inner array contains the messages in that thread

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`getPriorityInboxThreads()`

Retrieves all Priority Inbox threads irrespective of labels.

 Logger 
 . 
 log 
 ( 
 "# of messages in your Priority Inbox: " 
  
 + 
  
 GmailApp 
 . 
 getPriorityInboxThreads 
 () 
 . 
 length 
 );

Return

GmailThread[] — an array of Gmail threads in the Priority Inbox

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`getPriorityInboxThreads(start, max)`

Retrieves a range of Priority Inbox threads irrespective of labels.

 // Will log some number 2 or less 
 Logger 
 . 
 log 
 ( 
 "# of messages in your Priority Inbox: " 
  
 + 
  
 GmailApp 
 . 
 getPriorityInboxThreads 
 ( 
 0 
 , 
  
 2 
 ). 
 length 
 );

Parameters

Name	Type	Description
`start`	`Integer`	the index of the first thread to retrieve
`max`	`Integer`	the maximum number of threads to retrieve

Return

GmailThread[] — an array of Gmail threads in the Priority Inbox

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`getPriorityInboxUnreadCount()`

Gets the number of unread threads in the Priority Inbox.

Logger.log("Number of unread emails in your Priority Inbox : " +
           GmailApp.getPriorityInboxUnreadCount());

Return

Integer — the number of threads in the Priority Inbox that have unread messages

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`getSpamThreads()`

Retrieves all spam threads irrespective of labels.

 Logger 
 . 
 log 
 ( 
 "# of total spam threads: " 
  
 + 
  
 GmailApp 
 . 
 getSpamThreads 
 () 
 . 
 length 
 );

Return

GmailThread[] — an array of Gmail threads in the spam folder

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`getSpamThreads(start, max)`

Retrieves a range of spam threads irrespective of labels.

 // Will log a number at most 5 
 Logger 
 . 
 log 
 ( 
 "# of total spam threads: " 
  
 + 
  
 GmailApp 
 . 
 getSpamThreads 
 ( 
 0 
 , 
  
 5 
 ). 
 length 
 );

Parameters

Name	Type	Description
`start`	`Integer`	the index of the first thread to retrieve
`max`	`Integer`	the maximum number of threads to retrieve

Return

GmailThread[] — an array of Gmail threads in the spam folder

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`getSpamUnreadCount()`

Gets the number of unread threads that are spam.

 // Unless you actually read stuff in your spam folder, this should be the same as 
 // the number of messages in your spam folder. 
 Logger 
 . 
 log 
 ( 
 "# unread threads that are spam: " 
  
 + 
  
 GmailApp 
 . 
 getSpamUnreadCount 
 ());

Return

Integer — the number spam threads that have unread messages

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`getStarredThreads()`

Retrieves all starred threads irrespective of labels.

 // Logs the number of starred threads 
 Logger 
 . 
 log 
 ( 
 "# Starred threads: " 
  
 + 
  
 GmailApp 
 . 
 getStarredThreads 
 (). 
 length 
 );

Return

GmailThread[] — an array of starred Gmail threads

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`getStarredThreads(start, max)`

Retrieves a range of starred threads irrespective of labels.

 // Logs the number of starred threads to a maximum of 5 
 Logger 
 . 
 log 
 ( 
 "# Starred threads: " 
  
 + 
  
 GmailApp 
 . 
 getStarredThreads 
 ( 
 0 
 , 
  
 5 
 ). 
 length 
 );

Parameters

Name	Type	Description
`start`	`Integer`	the index of the first thread to retrieve
`max`	`Integer`	the maximum number of threads to retrieve

Return

GmailThread[] — an array of starred Gmail threads

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`getStarredUnreadCount()`

Gets the number of unread threads that are starred.

 Logger 
 . 
 log 
 ( 
 "# unread and starred: " 
  
 + 
  
 GmailApp 
 . 
 getStarredUnreadCount 
 ());

Return

Integer — the number of starred threads that have unread messages

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`getThreadById(id)`

Gets a thread by ID.

Use this in conjunction with getId() on Gmail threads.

 // 
  
 Gets 
  
 the 
  
 first 
  
 inbox 
  
 thread 
 . 
 const 
  
 firstThread 
  
 = 
  
 GmailApp 
 . 
 getInboxThreads 
 ( 
 0 
 , 
 1 
 )[ 
 0 
 ]; 
 // 
  
 Gets 
  
 the 
  
 same 
  
 thread 
  
 by 
  
 ID 
 . 
 const 
  
 threadById 
  
 = 
  
 GmailApp 
 . 
 getThreadById 
 ( 
 firstThread 
 . 
 getId 
 ()); 
 // 
  
 Verifies 
  
 that 
  
 they 
  
 are 
  
 the 
  
 same 
 . 
 console 
 . 
 log 
 ( 
 firstThread 
 . 
 getFirstMessageSubject 
 () 
  
 === 
  
 threadById 
 . 
 getFirstMessageSubject 
 ());

Parameters

Name	Type	Description
`id`	`String`	The ID of the thread to retrieve.

Return

GmailThread — The thread with the given ID or null if not found.

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`getTrashThreads()`

Retrieves all trash threads irrespective of labels.

 Logger 
 . 
 log 
 ( 
 "# of total trash threads: " 
  
 + 
  
 GmailApp 
 . 
 getTrashThreads 
 () 
 . 
 length 
 );

Return

GmailThread[] — an array of Gmail threads in the trash

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`getTrashThreads(start, max)`

Retrieves a range of trash threads irrespective of labels.

 // Will log a number at most 5 
 Logger 
 . 
 log 
 ( 
 "# of total trash threads: " 
  
 + 
  
 GmailApp 
 . 
 getTrashThreads 
 ( 
 0 
 , 
  
 5 
 ). 
 length 
 );

Parameters

Name	Type	Description
`start`	`Integer`	the index of the first thread to retrieve
`max`	`Integer`	the maximum number of threads to retrieve

Return

GmailThread[] — an array of Gmail threads in the trash

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`getUserLabelByName(name)`

Retrieves a label given the label name.

 var 
  
 labelObject 
  
 = 
  
 GmailApp 
 . 
 getUserLabelByName 
 ( 
 "myLabel" 
 );

Parameters

Name	Type	Description
`name`	`String`	the name of the label to retrieve

Return

GmailLabel — the Gmail label with the given name

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`getUserLabels()`

Retrieves a list of user-created labels.

 // 
  
 Logs 
  
 all 
  
 of 
  
 the 
  
 names 
  
 of 
  
 your 
  
 labels 
 var 
  
 labels 
  
 = 
  
 GmailApp 
 . 
 getUserLabels 
 (); 
 for 
  
 ( 
 var 
  
 i 
  
 = 
  
 0 
 ; 
  
 i 
 < 
 labels 
 . 
 length 
 ; 
  
 i 
 ++ 
 ) 
  
 { 
  
 Logger 
 . 
 log 
 ( 
 "label: " 
  
 + 
  
 labels 
 [ 
 i 
 ] 
 . 
 getName 
 ()); 
 }

Return

GmailLabel[] — array of user created labels

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`markMessageRead(message)`

Marks this message read and forces the message to refresh.

 // 
  
 Mark 
  
 the 
  
 first 
  
 message 
  
 in 
  
 the 
  
 first 
  
 thread 
  
 of 
  
 your 
  
 inbox 
  
 as 
  
 read 
 var 
  
 message 
  
 = 
  
 GmailApp 
 . 
 getInboxThreads 
 ( 
 0 
 , 
  
 1 
 )[ 
 0 
 ] 
 . 
 getMessages 
 ()[ 
 0 
 ]; 
 GmailApp 
 . 
 markMessageRead 
 ( 
 message 
 );

Parameters

Name	Type	Description
`message`	`GmailMessage`	the message to mark as read

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`markMessageUnread(message)`

Marks this message unread and forces the message to refresh.

 // 
  
 Mark 
  
 the 
  
 first 
  
 message 
  
 in 
  
 the 
  
 first 
  
 thread 
  
 of 
  
 your 
  
 inbox 
  
 as 
  
 unread 
 var 
  
 message 
  
 = 
  
 GmailApp 
 . 
 getInboxThreads 
 ( 
 0 
 , 
  
 1 
 )[ 
 0 
 ] 
 . 
 getMessages 
 ()[ 
 0 
 ]; 
 GmailApp 
 . 
 markMessageUnread 
 ( 
 message 
 );

Parameters

Name	Type	Description
`message`	`GmailMessage`	the message to mark as unread

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`markMessagesRead(messages)`

Marks these messages read and forces the messages to refresh.

 // 
  
 Mark 
  
 first 
  
 three 
  
 messages 
  
 in 
  
 the 
  
 first 
  
 inbox 
  
 thread 
  
 as 
  
 read 
 . 
 // 
  
 Assumes 
  
 that 
  
 the 
  
 first 
  
 inbox 
  
 thread 
  
 has 
  
 3 
  
 messages 
  
 in 
  
 it 
 . 
 var 
  
 threadMessages 
  
 = 
  
 GmailApp 
 . 
 getInboxThreads 
 ( 
 0 
 , 
  
 1 
 )[ 
 0 
 ] 
 . 
 getMessages 
 (); 
 var 
  
 messages 
  
 = 
  
 [ 
 threadMessages 
 [ 
 0 
 ], 
  
 threadMessages 
 [ 
 1 
 ], 
  
 threadMessages 
 [ 
 2 
 ]]; 
 GmailApp 
 . 
 markMessagesRead 
 ( 
 thread 
 . 
 getMessages 
 ());

Parameters

Name	Type	Description
`messages`	`GmailMessage[]`	an array of messages to mark as read

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`markMessagesUnread(messages)`

Marks these messages unread and forces the messages to refresh.

 // 
  
 Mark 
  
 first 
  
 three 
  
 messages 
  
 in 
  
 the 
  
 first 
  
 inbox 
  
 thread 
  
 as 
  
 unread 
 . 
 // 
  
 Assumes 
  
 that 
  
 the 
  
 first 
  
 inbox 
  
 thread 
  
 has 
  
 3 
  
 messages 
  
 in 
  
 it 
 var 
  
 threadMessages 
  
 = 
  
 GmailApp 
 . 
 getInboxThreads 
 ( 
 0 
 , 
  
 1 
 )[ 
 0 
 ] 
 . 
 getMessages 
 (); 
 var 
  
 messages 
  
 = 
  
 [ 
 threadMessages 
 [ 
 0 
 ], 
  
 threadMessages 
 [ 
 1 
 ], 
  
 threadMessages 
 [ 
 2 
 ]]; 
 GmailApp 
 . 
 markMessagesUnread 
 ( 
 thread 
 . 
 getMessages 
 ());

Parameters

Name	Type	Description
`messages`	`GmailMessage[]`	an array of messages to mark as unread

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`markThreadImportant(thread)`

Marks this thread as important and forces the thread to refresh.

 // 
  
 Marks 
  
 first 
  
 inbox 
  
 thread 
  
 as 
  
 important 
 var 
  
 thread 
  
 = 
  
 GmailApp 
 . 
 getInboxThreads 
 ( 
 0 
 , 
  
 1 
 )[ 
 0 
 ]; 
 GmailApp 
 . 
 markThreadImportant 
 ( 
 thread 
 );

Parameters

Name	Type	Description
`thread`	`GmailThread`	the thread to mark as important

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`markThreadRead(thread)`

Marks this thread as read and forces the thread to refresh.

 // 
  
 Marks 
  
 first 
  
 inbox 
  
 thread 
  
 as 
  
 read 
 var 
  
 thread 
  
 = 
  
 GmailApp 
 . 
 getInboxThreads 
 ( 
 0 
 , 
  
 1 
 )[ 
 0 
 ]; 
 GmailApp 
 . 
 markThreadRead 
 ( 
 thread 
 );

Parameters

Name	Type	Description
`thread`	`GmailThread`	the thread to mark as read

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`markThreadUnimportant(thread)`

Marks this thread as unimportant and forces the thread to refresh.

 // 
  
 Marks 
  
 first 
  
 inbox 
  
 thread 
  
 as 
  
 unimportant 
 var 
  
 thread 
  
 = 
  
 GmailApp 
 . 
 getInboxThreads 
 ( 
 0 
 , 
  
 1 
 )[ 
 0 
 ]; 
 GmailApp 
 . 
 markThreadUnimportant 
 ( 
 thread 
 );

Parameters

Name	Type	Description
`thread`	`GmailThread`	the thread to mark as unimportant

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`markThreadUnread(thread)`

Marks this thread unread and forces the thread to refresh.

 // 
  
 Marks 
  
 first 
  
 inbox 
  
 thread 
  
 as 
  
 unread 
 var 
  
 thread 
  
 = 
  
 GmailApp 
 . 
 getInboxThreads 
 ( 
 0 
 , 
  
 1 
 )[ 
 0 
 ]; 
 GmailApp 
 . 
 markThreadUnread 
 ( 
 thread 
 );

Parameters

Name	Type	Description
`thread`	`GmailThread`	the thread to mark as unread

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`markThreadsImportant(threads)`

Marks these threads as important and forces the threads to refresh.

 // 
  
 Marks 
  
 first 
  
 two 
  
 threads 
  
 in 
  
 inbox 
  
 as 
  
 important 
 var 
  
 threads 
  
 = 
  
 GmailApp 
 . 
 getInboxThreads 
 ( 
 0 
 , 
  
 2 
 ); 
 GmailApp 
 . 
 markThreadsImportant 
 ( 
 threads 
 );

Parameters

Name	Type	Description
`threads`	`GmailThread[]`	an array of threads to mark as important

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`markThreadsRead(threads)`

Marks these threads as read and forces the threads to refresh.

 // 
  
 Marks 
  
 first 
  
 two 
  
 threads 
  
 in 
  
 inbox 
  
 as 
  
 read 
 var 
  
 threads 
  
 = 
  
 GmailApp 
 . 
 getInboxThreads 
 ( 
 0 
 , 
  
 2 
 ); 
 GmailApp 
 . 
 markThreadsRead 
 ( 
 threads 
 );

Parameters

Name	Type	Description
`threads`	`GmailThread[]`	an array of threads to mark as read

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`markThreadsUnimportant(threads)`

Marks these threads as unimportant and forces the threads to refresh.

 // 
  
 Marks 
  
 first 
  
 two 
  
 threads 
  
 in 
  
 inbox 
  
 as 
  
 unimportant 
 var 
  
 threads 
  
 = 
  
 GmailApp 
 . 
 getInboxThreads 
 ( 
 0 
 , 
  
 2 
 ); 
 GmailApp 
 . 
 markThreadsUnimportant 
 ( 
 threads 
 );

Parameters

Name	Type	Description
`threads`	`GmailThread[]`	an array of threads to mark as unimportant

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`markThreadsUnread(threads)`

Marks these threads as unread and forces the threads to refresh.

 // 
  
 Marks 
  
 first 
  
 two 
  
 threads 
  
 in 
  
 inbox 
  
 as 
  
 unread 
 var 
  
 threads 
  
 = 
  
 GmailApp 
 . 
 getInboxThreads 
 ( 
 0 
 , 
  
 2 
 ); 
 GmailApp 
 . 
 markThreadsUnread 
 ( 
 threads 
 );

Parameters

Name	Type	Description
`threads`	`GmailThread[]`	an array of threads to mark as unread

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`moveMessageToTrash(message)`

Moves the message to the trash and forces the message to refresh.

 // 
  
 Move 
  
 the 
  
 first 
  
 message 
  
 in 
  
 your 
  
 inbox 
  
 to 
  
 trash 
 var 
  
 firstThread 
  
 = 
  
 GmailApp 
 . 
 getInboxThreads 
 ( 
 0 
 , 
 1 
 )[ 
 0 
 ]; 
 var 
  
 firstMessage 
  
 = 
  
 firstThread 
 . 
 getMessages 
 ()[ 
 0 
 ]; 
 GmailApp 
 . 
 moveMessageToTrash 
 ( 
 firstMessage 
 );

Parameters

Name	Type	Description
`message`	`GmailMessage`	the message to be trashed

Return

GmailApp — the Gmail service (useful for chaining)

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`moveMessagesToTrash(messages)`

Moves the specified messages to the trash and forces the messages to refresh.

 // 
  
 Move 
  
 first 
  
 two 
  
 messages 
  
 in 
  
 your 
  
 inbox 
  
 to 
  
 trash 
 var 
  
 firstThread 
  
 = 
  
 GmailApp 
 . 
 getInboxThreads 
 ( 
 0 
 , 
 1 
 )[ 
 0 
 ]; 
 var 
  
 messages 
  
 = 
  
 firstThread 
 . 
 getMessages 
 (); 
 var 
  
 toDelete 
  
 = 
  
 [ 
 messages 
 [ 
 0 
 ], 
  
 messages 
 [ 
 1 
 ]]; 
 GmailApp 
 . 
 moveMessagesToTrash 
 ( 
 toDelete 
 );

Parameters

Name	Type	Description
`messages`	`GmailMessage[]`	the messages to be trashed

Return

GmailApp — the Gmail service (useful for chaining)

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`moveThreadToArchive(thread)`

Moves this thread to the archive and forces the thread to refresh.

 // 
  
 Archive 
  
 the 
  
 first 
  
 thread 
  
 in 
  
 your 
  
 inbox 
 var 
  
 firstThread 
  
 = 
  
 GmailApp 
 . 
 getInboxThreads 
 ( 
 0 
 , 
 1 
 )[ 
 0 
 ]; 
 GmailApp 
 . 
 moveThreadToArchive 
 ( 
 firstThread 
 );

Parameters

Name	Type	Description
`thread`	`GmailThread`	the thread to be archive

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`moveThreadToInbox(thread)`

Moves this thread to the inbox and forces the thread to refresh.

 // 
  
 Find 
  
 a 
  
 thread 
  
 not 
  
 already 
  
 in 
  
 your 
  
 inbox 
 var 
  
 thread 
  
 = 
  
 GmailApp 
 . 
 search 
 ( 
 "-in:inbox" 
 )[ 
 0 
 ]; 
  
 // 
  
 Get 
  
 the 
  
 first 
  
 one 
 GmailApp 
 . 
 moveThreadToInbox 
 ( 
 thread 
 );

Parameters

Name	Type	Description
`thread`	`GmailThread`	the thread to be moved to the inbox

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`moveThreadToSpam(thread)`

Moves this thread to spam and forces the thread to refresh.

 // 
  
 Tag 
  
 first 
  
 thread 
  
 in 
  
 inbox 
  
 as 
  
 spam 
 var 
  
 firstThread 
  
 = 
  
 GmailApp 
 . 
 getInboxThreads 
 ( 
 0 
 , 
 1 
 )[ 
 0 
 ]; 
 GmailApp 
 . 
 moveThreadToSpam 
 ( 
 firstThread 
 );

Parameters

Name	Type	Description
`thread`	`GmailThread`	the thread to be moved to spam

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`moveThreadToTrash(thread)`

Moves this thread to the trash and forces the thread to refresh.

 // 
  
 Move 
  
 first 
  
 thread 
  
 in 
  
 inbox 
  
 to 
  
 trash 
 var 
  
 firstThread 
  
 = 
  
 GmailApp 
 . 
 getInboxThreads 
 ( 
 0 
 , 
 1 
 )[ 
 0 
 ]; 
 GmailApp 
 . 
 moveThreadToTrash 
 ( 
 firstThread 
 );

Parameters

Name	Type	Description
`thread`	`GmailThread`	the thread to be trashed

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`moveThreadsToArchive(threads)`

Moves these threads to the archive and forces the threads to refresh.

 // 
  
 Move 
  
 first 
  
 two 
  
 threads 
  
 in 
  
 your 
  
 inbox 
  
 to 
  
 the 
  
 archive 
 var 
  
 firstTwoThreads 
  
 = 
  
 GmailApp 
 . 
 getInboxThreads 
 ( 
 0 
 , 
 2 
 ); 
 GmailApp 
 . 
 moveThreadsToArchive 
 ( 
 firstTwoThreads 
 );

Parameters

Name	Type	Description
`threads`	`GmailThread[]`	an array of threads to be archived

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`moveThreadsToInbox(threads)`

Moves these threads to the inbox and forces the threads to refresh.

 // 
  
 Find 
  
 two 
  
 threads 
  
 not 
  
 already 
  
 in 
  
 your 
  
 inbox 
 var 
  
 firstTwoThreads 
  
 = 
  
 GmailApp 
 . 
 search 
 ( 
 "-in:inbox" 
 , 
  
 0 
 , 
  
 2 
 ); 
 GmailApp 
 . 
 moveThreadsToInbox 
 ( 
 firstTwoThreads 
 );

Parameters

Name	Type	Description
`threads`	`GmailThread[]`	an array of threads to be moved to the inbox

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`moveThreadsToSpam(threads)`

Moves these threads to spam and forces the threads to refresh.

 // 
  
 Move 
  
 first 
  
 two 
  
 threads 
  
 in 
  
 your 
  
 inbox 
  
 to 
  
 spam 
 var 
  
 firstTwoThreads 
  
 = 
  
 GmailApp 
 . 
 getInboxThreads 
 ( 
 0 
 , 
 2 
 ); 
 GmailApp 
 . 
 moveThreadsToSpam 
 ( 
 firstTwoThreads 
 );

Parameters

Name	Type	Description
`threads`	`GmailThread[]`	an array of threads to be moved to spam

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`moveThreadsToTrash(threads)`

Moves these threads to the trash and forces the threads to refresh.

 // 
  
 Move 
  
 first 
  
 two 
  
 threads 
  
 in 
  
 your 
  
 inbox 
  
 to 
  
 trash 
 var 
  
 firstTwoThreads 
  
 = 
  
 GmailApp 
 . 
 getInboxThreads 
 ( 
 0 
 , 
 2 
 ); 
 GmailApp 
 . 
 moveThreadsToTrash 
 ( 
 firstTwoThreads 
 );

Parameters

Name	Type	Description
`threads`	`GmailThread[]`	an array of threads to be trashed

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`refreshMessage(message)`

Reloads the message and associated state from Gmail (useful in case the labels, read state, etc., have changed).

 var 
  
 firstThread 
  
 = 
  
 GmailApp 
 . 
 getInboxThreads 
 ( 
 0 
 , 
 1 
 )[ 
 0 
 ]; 
 var 
  
 firstMessage 
  
 = 
  
 firstThread 
 . 
 getMessages 
 ()[ 
 0 
 ]; 
 // 
  
 ... 
 Do 
  
 something 
  
 that 
  
 may 
  
 take 
  
 a 
  
 while 
  
 here 
 .... 
 GmailApp 
 . 
 refreshMessage 
 ( 
 firstMessage 
 ); 
 // 
  
 ... 
 Do 
  
 more 
  
 stuff 
  
 with 
  
 firstMessage 
 ...

Parameters

Name	Type	Description
`message`	`GmailMessage`	the message to be refreshed

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`refreshMessages(messages)`

Reloads the messages and associated state from Gmail (useful in case the labels, read state, etc., have changed).

 var 
  
 firstThread 
  
 = 
  
 GmailApp 
 . 
 getInboxThreads 
 ( 
 0 
 , 
 1 
 )[ 
 0 
 ]; 
 var 
  
 coupleOfMessages 
  
 = 
  
 firstThread 
 . 
 getMessages 
 () 
 . 
 slice 
 ( 
 0 
 , 
  
 2 
 ); 
 // 
  
 ... 
 Do 
  
 something 
  
 that 
  
 may 
  
 take 
  
 a 
  
 while 
  
 here 
 .... 
 GmailApp 
 . 
 refreshMessages 
 ( 
 coupleOfMessages 
 ); 
 // 
  
 ... 
 Do 
  
 more 
  
 stuff 
  
 with 
  
 coupleOfMessages 
 ...

Parameters

Name	Type	Description
`messages`	`GmailMessage[]`	the messages to be refreshed

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`refreshThread(thread)`

Reloads the thread and associated state from Gmail (useful in case the labels, read state, etc., have changed).

 var 
  
 firstThread 
  
 = 
  
 GmailApp 
 . 
 getInboxThreads 
 ( 
 0 
 , 
 1 
 )[ 
 0 
 ]; 
 // 
  
 ... 
 Do 
  
 something 
  
 that 
  
 may 
  
 take 
  
 a 
  
 while 
  
 here 
 .... 
 GmailApp 
 . 
 refreshThread 
 ( 
 firstThread 
 ); 
 // 
  
 ... 
  
 Do 
  
 more 
  
 stuff 
  
 with 
  
 the 
  
 thread 
  
 ...

Parameters

Name	Type	Description
`thread`	`GmailThread`	the thread to be refreshed

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`refreshThreads(threads)`

Reloads the threads and associated state from Gmail (useful in case the labels, read state, etc., have changed).

 var 
  
 threads 
  
 = 
  
 GmailApp 
 . 
 getInboxThreads 
 ( 
 0 
 , 
  
 3 
 ); 
 // 
  
 ... 
 Do 
  
 something 
  
 that 
  
 may 
  
 take 
  
 a 
  
 while 
  
 here 
 .... 
 GmailApp 
 . 
 refreshThreads 
 ( 
 threads 
 ); 
 // 
  
 ... 
  
 Do 
  
 more 
  
 stuff 
  
 with 
  
 threads 
  
 ...

Parameters

Name	Type	Description
`threads`	`GmailThread[]`	the threads to be refreshed

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`search(query)`

Search Gmail with the given query.

 // 
  
 Find 
  
 starred 
  
 messages 
  
 with 
  
 subject 
  
 IMPORTANT 
 var 
  
 threads 
  
 = 
  
 GmailApp 
 . 
 search 
 ( 
 'is:starred subject:"IMPORTANT"' 
 );

Parameters

Name	Type	Description
`query`	`String`	the search query, as you would type it into Gmail

Return

GmailThread[] — an array of Gmail threads matching this query

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`search(query, start, max)`

Search Gmail with the given query.

 // 
  
 Find 
  
 starred 
  
 messages 
  
 with 
  
 subject 
  
 IMPORTANT 
  
 and 
  
 return 
  
 second 
  
 batch 
  
 of 
  
 10. 
 // 
  
 Assumes 
  
 there 
  
 are 
  
 at 
  
 least 
  
 11 
  
 of 
  
 them 
 , 
  
 otherwise 
  
 this 
  
 will 
  
 return 
  
 an 
  
 empty 
  
 array 
 . 
 var 
  
 threads 
  
 = 
  
 GmailApp 
 . 
 search 
 ( 
 'is:starred subject:"IMPORTANT"' 
 , 
  
 10 
 , 
  
 10 
 );

Parameters

Name	Type	Description
`query`	`String`	the search query, as you would type it into Gmail
`start`	`Integer`	the index of the starting thread
`max`	`Integer`	the maximum number of threads to return

Return

GmailThread[] — an array of Gmail threads matching this query

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`sendEmail(recipient, subject, body)`

Sends an email message. The size of the email (including headers) is quota limited .

 // 
  
 The 
  
 code 
  
 below 
  
 will 
  
 send 
  
 an 
  
 email 
  
 with 
  
 the 
  
 current 
  
 date 
  
 and 
  
 time 
 . 
 var 
  
 now 
  
 = 
  
 new 
  
 Date 
 (); 
 GmailApp 
 . 
 sendEmail 
 ( 
 "mike@example.com" 
 , 
  
 "current time" 
 , 
  
 "The time is: " 
  
 + 
  
 now 
 . 
 toString 
 ());

Parameters

Name	Type	Description
`recipient`	`String`	comma separated list of email addresses
`subject`	`String`	subject of the email (250 characters maximum)
`body`	`String`	body of the email

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`sendEmail(recipient, subject, body, options)`

Sends an email message with optional arguments. The email can contain plain text or an HTML body. The size of the email (including headers, but excluding attachments) is quota limited .

 // 
  
 Send 
  
 an 
  
 email 
  
 with 
  
 a 
  
 file 
  
 from 
  
 Google 
  
 Drive 
  
 attached 
  
 as 
  
 a 
  
 PDF 
 . 
 var 
  
 file 
  
 = 
  
 DriveApp 
 . 
 getFileById 
 ( 
 '1234567890abcdefghijklmnopqrstuvwxyz' 
 ); 
 GmailApp 
 . 
 sendEmail 
 ( 
 'mike@example.com' 
 , 
  
 'Attachment example' 
 , 
  
 'Please see the attached file.' 
 , 
  
 { 
  
 attachments 
 : 
  
 [ 
 file 
 . 
 getAs 
 ( 
 MimeType 
 . 
 PDF 
 )], 
  
 name 
 : 
  
 'Automatic Emailer Script' 
 });

Parameters

Name	Type	Description
`recipient`	`String`	the addresses of the recipient
`subject`	`String`	the subject line (250 characters maximum)
`body`	`String`	the body of the email
`options`	`Object`	a JavaScript object that specifies advanced parameters, as listed below

Advanced parameters

Name	Type	Description
`attachments`	`BlobSource[]`	an array of files to send with the email
`bcc`	`String`	a comma-separated list of email addresses to BCC
`cc`	`String`	a comma-separated list of email addresses to CC
`from`	`String`	the address that the email should be sent from, which must be one of the values returned by `getAliases()`
`htmlBody`	`String`	if set, devices capable of rendering HTML will use it instead of the required body argument; you can add an optional `inlineImages` field in HTML body if you have inlined images for your email
`inlineImages`	`Object`	a JavaScript object containing a mapping from image key ( `String` ) to image data ( `BlobSource` ); this assumes that the `htmlBody` parameter is used and contains references to these images in the format `<img src="cid:imageKey" />`
`name`	`String`	the name of the sender of the email (default: the user's name)
`noReply`	`Boolean`	`true` if the email should be sent from a generic no-reply email address to discourage recipients from responding to emails; this option is only possible for Google Workspace accounts, not Gmail users
`replyTo`	`String`	an email address to use as the default reply-to address (default: the user's email address)

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`setCurrentMessageAccessToken(accessToken)`

Sets the current message access token that enables the script to access the current GmailMessage properties.

Only Google Workspace Add-on projects using Gmail current message scopes require this method.

 function 
  
 handleAddonActionEvent 
 ( 
 e 
 ) 
  
 { 
  
 var 
  
 accessToken 
  
 = 
  
 e 
 . 
 messageMetadata 
 . 
 accessToken 
 ; 
  
 var 
  
 messageId 
  
 = 
  
 e 
 . 
 messageMetadata 
 . 
 messageId 
 ; 
  
 GmailApp 
 . 
 setCurrentMessageAccessToken 
 ( 
 accessToken 
 ); 
  
 var 
  
 mailMessage 
  
 = 
  
 GmailApp 
 . 
 getMessageById 
 ( 
 messageId 
 ); 
  
 // 
  
 Do 
  
 something 
  
 with 
  
 mailMessage 
 }

Parameters

Name	Type	Description
`accessToken`	`String`	the temporary access token obtained from a Gmail add-on action event object .

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`starMessage(message)`

Adds a star to this message and forces the message to refresh.

 // 
  
 Stars 
  
 the 
  
 first 
  
 message 
  
 in 
  
 the 
  
 first 
  
 thread 
  
 in 
  
 your 
  
 inbox 
 var 
  
 firstThread 
  
 = 
  
 GmailApp 
 . 
 getInboxThreads 
 ( 
 0 
 , 
 1 
 )[ 
 0 
 ]; 
 var 
  
 message 
  
 = 
  
 firstThread 
 . 
 getMessages 
 ()[ 
 0 
 ]; 
 GmailApp 
 . 
 starMessage 
 ( 
 message 
 );

Parameters

Name	Type	Description
`message`	`GmailMessage`	the message to star

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`starMessages(messages)`

Adds stars to these messages and forces the messages to refresh.

 // 
  
 Stars 
  
 the 
  
 first 
  
 three 
  
 messages 
  
 in 
  
 the 
  
 first 
  
 thread 
  
 in 
  
 your 
  
 inbox 
 var 
  
 firstThread 
  
 = 
  
 GmailApp 
 . 
 getInboxThreads 
 ( 
 0 
 , 
 1 
 )[ 
 0 
 ]; 
 var 
  
 coupleOfMessages 
  
 = 
  
 firstThread 
 . 
 getMessages 
 () 
 . 
 slice 
 ( 
 0 
 , 
  
 3 
 ); 
 GmailApp 
 . 
 starMessages 
 ( 
 coupleOfMessages 
 );

Parameters

Name	Type	Description
`messages`	`GmailMessage[]`	an array of messages to star

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`unstarMessage(message)`

Removes a star from this message and forces the message to refresh.

 // 
  
 Unstars 
  
 the 
  
 first 
  
 message 
  
 in 
  
 the 
  
 first 
  
 thread 
  
 in 
  
 your 
  
 inbox 
 var 
  
 firstThread 
  
 = 
  
 GmailApp 
 . 
 getInboxThreads 
 ( 
 0 
 , 
 1 
 )[ 
 0 
 ]; 
 var 
  
 message 
  
 = 
  
 firstThread 
 . 
 getMessages 
 ()[ 
 0 
 ]; 
 GmailApp 
 . 
 unstarMessage 
 ( 
 message 
 );

Parameters

Name	Type	Description
`message`	`GmailMessage`	the message to unstar

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`unstarMessages(messages)`

Removes stars from these messages and forces the messages to refresh.

 // 
  
 Unstars 
  
 the 
  
 first 
  
 three 
  
 messages 
  
 in 
  
 the 
  
 first 
  
 thread 
  
 in 
  
 your 
  
 inbox 
 var 
  
 firstThread 
  
 = 
  
 GmailApp 
 . 
 getInboxThreads 
 ( 
 0 
 , 
 1 
 )[ 
 0 
 ]; 
 var 
  
 coupleOfMessages 
  
 = 
  
 firstThread 
 . 
 getMessages 
 () 
 . 
 slice 
 ( 
 0 
 , 
  
 3 
 ); 
 GmailApp 
 . 
 unstarMessages 
 ( 
 coupleOfMessages 
 );

Parameters

Name	Type	Description
`messages`	`GmailMessage[]`	an array of messages to unstar

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

Deprecated methods

`getChatThreads()`

Deprecated.This function is deprecated and should not be used in new scripts.

Gets all classic Google Hangouts threads and Google Chat threads until Google switches all users of classic Hangouts to Chat later this year. To learn more, see Learn about the switch from classic Hangouts to Google Chat .

This call fails when the size of all threads is too large for the system to handle. Where the thread size is unknown, and potentially very large, use the 'paged' call, and specify ranges of the threads to retrieve in each call.

 var 
  
 threads 
  
 = 
  
 GmailApp 
 . 
 getChatThreads 
 (); 
 Logger 
 . 
 log 
 ( 
 "# of chat threads: " 
  
 + 
  
 threads 
 . 
 length 
 );

Return

GmailThread[] — An array of chat threads from Gmail.

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

`getChatThreads(start, max)`

Deprecated.This function is deprecated and should not be used in new scripts.

Gets a range of classic Google Hangouts threads and Google Chat threads until Google switches all users of classic Hangouts to Chat later this year. To learn more, see Learn about the switch from classic Hangouts to Google Chat .

 // 
  
 Get 
  
 first 
  
 50 
  
 chat 
  
 threads 
 var 
  
 threads 
  
 = 
  
 GmailApp 
 . 
 getChatThreads 
 ( 
 0 
 , 
 50 
 ); 
 // 
  
 Will 
  
 log 
  
 no 
  
 more 
  
 than 
  
 50.0 
 Logger 
 . 
 log 
 ( 
 threads 
 . 
 length 
 ); 
 Logger 
 . 
 log 
 ( 
 threads 
 [ 
 0 
 ] 
 . 
 getFirstMessageSubject 
 ());

Parameters

Name	Type	Description
`start`	`Integer`	the index of the first thread to retrieve
`max`	`Integer`	the maximum number of threads to retrieve

Return

GmailThread[] — an array of chat Gmail threads

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API :

https://mail.google.com/

Class GmailApp

Methods

Deprecated methods

Detailed documentation

createDraft(recipient, subject, body)

Parameters

Return

Authorization

See also

createDraft(recipient, subject, body, options)

Parameters

Advanced parameters

Return

Authorization

See also

createLabel(name)

Parameters

Return

Authorization

See also

deleteLabel(label)

Parameters

Return

Authorization

See also

getAliases()

Return

Authorization

See also

getDraft(draftId)

Parameters

Return

Throws

Authorization

getDraftMessages()

Return

Authorization

getDrafts()

Return

Authorization

getInboxThreads()

Return

Authorization

getInboxThreads(start, max)

Parameters

Return

Authorization

getInboxUnreadCount()

Return

Authorization

getMessageById(id)

Parameters

Return

Throws

Authorization

See also

getMessagesForThread(thread)

Parameters

Return

Authorization

See also

getMessagesForThreads(threads)

Parameters

Return

Authorization

See also

getPriorityInboxThreads()

Return

Authorization

getPriorityInboxThreads(start, max)

Parameters

Return

Authorization

getPriorityInboxUnreadCount()

Return

Authorization

getSpamThreads()

Return

Authorization

getSpamThreads(start, max)

`createDraft(recipient, subject, body)`

`createDraft(recipient, subject, body, options)`

`createLabel(name)`

`deleteLabel(label)`

`getAliases()`

`getDraft(draftId)`

`getDraftMessages()`

`getDrafts()`

`getInboxThreads()`

`getInboxThreads(start, max)`

`getInboxUnreadCount()`

`getMessageById(id)`

`getMessagesForThread(thread)`

`getMessagesForThreads(threads)`

`getPriorityInboxThreads()`

`getPriorityInboxThreads(start, max)`

`getPriorityInboxUnreadCount()`

`getSpamThreads()`

`getSpamThreads(start, max)`

`getSpamUnreadCount()`

`getStarredThreads()`

`getStarredThreads(start, max)`

`getStarredUnreadCount()`

`getThreadById(id)`

`getTrashThreads()`

`getTrashThreads(start, max)`

`getUserLabelByName(name)`

`getUserLabels()`

`markMessageRead(message)`

`markMessageUnread(message)`

`markMessagesRead(messages)`

`markMessagesUnread(messages)`

`markThreadImportant(thread)`

`markThreadRead(thread)`

`markThreadUnimportant(thread)`