Class GmailLabel

GmailLabel

A user-created label in a user's Gmail account.

Methods

Method Return type Brief description
addToThread(thread)
GmailLabel Adds this label to the given thread and forces the thread to refresh ( GmailThread.refresh() ).
addToThreads(threads)
GmailLabel Adds this label to the given threads and forces the threads to refresh.
deleteLabel()
void Deletes this label.
getName()
String Gets the name of this label.
getThreads()
GmailThread[] Gets the threads that are marked with this label.
getThreads(start, max)
GmailThread[] Gets a range of threads marked with this label.
getUnreadCount()
Integer Gets the number of unread threads tagged with this label.
removeFromThread(thread)
GmailLabel Removes this label from the given thread and forces the thread to refresh.
removeFromThreads(threads)
GmailLabel Removes this label from the given threads and forces the threads to refresh.

Detailed documentation

addToThread(thread)

Adds this label to the given thread and forces the thread to refresh ( GmailThread.refresh() ).

 // 
  
 label 
  
 the 
  
 first 
  
 thread 
  
 in 
  
 the 
  
 inbox 
  
 with 
  
 the 
  
 label 
  
 MyLabel 
 var 
  
 label 
  
 = 
  
 GmailApp 
 . 
 getUserLabelByName 
 ( 
 "MyLabel" 
 ); 
 var 
  
 firstThread 
  
 = 
  
 GmailApp 
 . 
 getInboxThreads 
 ( 
 0 
 , 
 1 
 )[ 
 0 
 ]; 
 label 
 . 
 addToThread 
 ( 
 firstThread 
 );

Parameters

Name Type Description
thread
GmailThread The thread to be labeled.

Return

GmailLabel — This label, 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/

See also

addToThreads(threads)

Adds this label to the given threads and forces the threads to refresh. You can add labels for up to 100 threads per batch.

 // 
  
 label 
  
 the 
  
 first 
  
 three 
  
 threads 
  
 in 
  
 the 
  
 inbox 
  
 with 
  
 the 
  
 label 
  
 MyLabel 
 var 
  
 label 
  
 = 
  
 GmailApp 
 . 
 getUserLabelByName 
 ( 
 "MyLabel" 
 ); 
 var 
  
 threads 
  
 = 
  
 GmailApp 
 . 
 getInboxThreads 
 ( 
 0 
 , 
 3 
 ); 
 label 
 . 
 addToThreads 
 ( 
 threads 
 );

Parameters

Name Type Description
threads
GmailThread[] An array of threads to be labeled.

Return

GmailLabel — This label, 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/

See also

deleteLabel()

Deletes this label.

 var 
  
 label 
  
 = 
  
 GmailApp 
 . 
 getUserLabelByName 
 ( 
 "MyLabel" 
 ); 
 label 
 . 
 deleteLabel 
 ();

Throws

Error — if the label can't be deleted

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/

See also

getName()

Gets the name of this label.

 var 
  
 label 
  
 = 
  
 GmailApp 
 . 
 getUserLabelByName 
 ( 
 "MyLabel" 
 ); 
 Logger 
 . 
 log 
 ( 
 label 
 . 
 getName 
 ()); 
  
 // 
 logs 
  
 MyLabel

Return

String — The name of the 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/

getThreads()

Gets the threads that are marked with this label.

This calls 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 getThreads(start, max) and specify ranges of the threads to retrieve in each call.

 // 
  
 Log 
  
 the 
  
 subject 
  
 lines 
  
 of 
  
 the 
  
 threads 
  
 labeled 
  
 with 
  
 MyLabel 
 var 
  
 label 
  
 = 
  
 GmailApp 
 . 
 getUserLabelByName 
 ( 
 "MyLabel" 
 ); 
 var 
  
 threads 
  
 = 
  
 label 
 . 
 getThreads 
 (); 
 for 
  
 ( 
 var 
  
 i 
  
 = 
  
 0 
 ; 
  
 i 
 < 
 threads 
 . 
 length 
 ; 
  
 i 
 ++ 
 ) 
  
 { 
  
 Logger 
 . 
 log 
 ( 
 threads 
 [ 
 i 
 ] 
 . 
 getFirstMessageSubject 
 ()); 
 }

Return

GmailThread[] — An array of threads marked with this 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/

getThreads(start, max)

Gets a range of threads marked with this label.

 // 
  
 log 
  
 the 
  
 subject 
  
 lines 
  
 of 
  
 up 
  
 to 
  
 the 
  
 first 
  
 30 
  
 threads 
  
 with 
  
 the 
  
 label 
  
 MyLabel 
 var 
  
 label 
  
 = 
  
 GmailApp 
 . 
 getUserLabelByName 
 ( 
 "MyLabel" 
 ); 
 var 
  
 threads 
  
 = 
  
 label 
 . 
 getThreads 
 ( 
 0 
 , 
  
 30 
 ); 
 for 
  
 ( 
 var 
  
 i 
  
 = 
  
 0 
 ; 
  
 i 
 < 
 threads 
 . 
 length 
 ; 
  
 i 
 ++ 
 ) 
  
 { 
  
 Logger 
 . 
 log 
 ( 
 threads 
 [ 
 i 
 ] 
 . 
 getFirstMessageSubject 
 ()); 
 }

Parameters

Name Type Description
start
Integer The index of the starting thread.
max
Integer The maximum number of threads to return.

Return

GmailThread[] — An array of threads marked with this 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/

getUnreadCount()

Gets the number of unread threads tagged with this label.

 // 
  
 log 
  
 the 
  
 number 
  
 of 
  
 unread 
  
 threads 
  
 labeled 
  
 with 
  
 MyLabel 
 var 
  
 label 
  
 = 
  
 GmailApp 
 . 
 getUserLabelByName 
 ( 
 "MyLabel" 
 ); 
 Logger 
 . 
 log 
 ( 
 label 
 . 
 getUnreadCount 
 ());

Return

Integer — The number of unread labeled 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/

removeFromThread(thread)

Removes this label from the given thread and forces the thread to refresh.

 // 
  
 remove 
  
 the 
  
 label 
  
 MyLabel 
  
 from 
  
 the 
  
 first 
  
 thread 
  
 in 
  
 the 
  
 inbox 
 var 
  
 label 
  
 = 
  
 GmailApp 
 . 
 getUserLabelByName 
 ( 
 "MyLabel" 
 ); 
 var 
  
 firstThread 
  
 = 
  
 GmailApp 
 . 
 getInboxThreads 
 ( 
 0 
 , 
 1 
 )[ 
 0 
 ]; 
 label 
 . 
 removeFromThread 
 ( 
 firstThread 
 );

Parameters

Name Type Description
thread
GmailThread The thread be unlabeled.

Return

GmailLabel — This label, 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/

See also

removeFromThreads(threads)

Removes this label from the given threads and forces the threads to refresh. You can remove labels for up to 100 threads per batch.

 // 
  
 remove 
  
 the 
  
 label 
  
 MyLabel 
  
 from 
  
 the 
  
 first 
  
 three 
  
 threads 
  
 in 
  
 the 
  
 inbox 
 var 
  
 label 
  
 = 
  
 GmailApp 
 . 
 getUserLabelByName 
 ( 
 "MyLabel" 
 ); 
 var 
  
 threads 
  
 = 
  
 GmailApp 
 . 
 getInboxThreads 
 ( 
 0 
 , 
 3 
 ); 
 label 
 . 
 removeFromThreads 
 ( 
 threads 
 );

Parameters

Name Type Description
threads
GmailThread[] An array of threads to be unlabeled.

Return

GmailLabel — This label, 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/

See also