Class GmailLabel

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

  • Gmail Labels have methods to add or remove themselves from individual threads or multiple threads.

  • You can delete a Gmail label.

  • You can retrieve the ID or name of a Gmail label.

  • You can get the threads associated with a label or a range of threads, and also get the count of unread threads with that label.

GmailLabel

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

Methods

MethodReturn typeBrief description
addToThread(thread)GmailLabelAdds this label to the given thread and forces the thread to refresh (GmailThread.refresh()).
addToThreads(threads)GmailLabelAdds this label to the given threads and forces the threads to refresh.
deleteLabel()voidDeletes this label.
getId()StringGets the id of this label.
getName()StringGets 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()IntegerGets the number of unread threads tagged with this label.
removeFromThread(thread)GmailLabelRemoves this label from the given thread and forces the thread to refresh.
removeFromThreads(threads)GmailLabelRemoves 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 MyLabelconstlabel=GmailApp.getUserLabelByName('MyLabel');constfirstThread=GmailApp.getInboxThreads(0,1)[0];label.addToThread(firstThread);

Parameters

NameTypeDescription
threadGmailThreadThe thread to be labeled.

Return

GmailLabel — This label, for chaining.

Authorization

Scripts that use this method require authorization with one or more of the followingscopes or appropriate scopes from therelated 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 forup to 100 threads per batch.

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

Parameters

NameTypeDescription
threadsGmailThread[]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 followingscopes or appropriate scopes from therelated REST API:

  • https://mail.google.com/

See also

deleteLabel()

Deletes this label.

constlabel=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 followingscopes or appropriate scopes from therelated REST API:

  • https://mail.google.com/

See also

getId()

Gets the id of this label.

constlabel=GmailApp.getUserLabelByName('MyLabel');console.log(label.getId());

Return

String — The id of the label.

Authorization

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

  • https://mail.google.com/

getName()

Gets the name of this label.

constlabel=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 followingscopes or appropriate scopes from therelated 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. Wherethe thread size is unknown, and potentially very large, please usegetThreads(start, max) and specify ranges of the threads to retrieve in each call.

// Log the subject lines of the threads labeled with MyLabelconstlabel=GmailApp.getUserLabelByName('MyLabel');constthreads=label.getThreads();for(leti=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 followingscopes or appropriate scopes from therelated 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 MyLabelconstlabel=GmailApp.getUserLabelByName('MyLabel');constthreads=label.getThreads(0,30);for(leti=0;i <threads.length;i++){Logger.log(threads[i].getFirstMessageSubject());}

Parameters

NameTypeDescription
startIntegerThe index of the starting thread.
maxIntegerThe 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 followingscopes or appropriate scopes from therelated 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 MyLabelconstlabel=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 followingscopes or appropriate scopes from therelated 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 inboxconstlabel=GmailApp.getUserLabelByName('MyLabel');constfirstThread=GmailApp.getInboxThreads(0,1)[0];label.removeFromThread(firstThread);

Parameters

NameTypeDescription
threadGmailThreadThe thread be unlabeled.

Return

GmailLabel — This label, for chaining.

Authorization

Scripts that use this method require authorization with one or more of the followingscopes or appropriate scopes from therelated 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 removelabels for up to 100 threads per batch.

// remove the label MyLabel from the first three threads in the inboxconstlabel=GmailApp.getUserLabelByName('MyLabel');constthreads=GmailApp.getInboxThreads(0,3);label.removeFromThreads(threads);

Parameters

NameTypeDescription
threadsGmailThread[]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 followingscopes or appropriate scopes from therelated REST API:

  • https://mail.google.com/

See also

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.