Object reference

Gmail label

A Gmail label is a tag you can apply to conversations. A script can look one up by name, and can add or remove it from threads.

GmailApp.GmailLabel

Start here

Get this object first

Look up a label by its exact name. If it does not exist yet, create it so the rest of the script always has a label to use.

Code.gs

function getOrCreateProcessedLabel() {
  const labelName = 'Processed by script';
  let label = GmailApp.getUserLabelByName(labelName);
  if (!label) {
    label = GmailApp.createLabel(labelName);
  }
  Logger.log(label.getName());
}

Then use it

Common actions

Choose an action, then open its example only when you need the code.

Count the threads carrying a label

Logs the number of conversations that have the label.

GmailApp.GmailLabel

Show example code

Code.gs

function logProcessedLabelThreadCount() {
  const label = GmailApp.getUserLabelByName('Processed by script');
  if (!label) throw new Error('Create a Gmail label named Processed by script first.');
  Logger.log(label.getThreads().length);
}

Add the label to a thread (this changes data)

Adds the label to the newest matching conversation. Nothing is deleted or sent.

GmailApp.GmailLabelGmailApp.GmailThread

Show example code

Code.gs

function addProcessedLabelToLatestThread() {
  const label = GmailApp.getUserLabelByName('Processed by script');
  if (!label) throw new Error('Create a Gmail label named Processed by script first.');
  const threads = GmailApp.search('newer_than:1d', 0, 1);
  if (!threads.length) return;
  label.addToThread(threads[0]);
  Logger.log('Label added to: ' + threads[0].getFirstMessageSubject());
}

List all of your label names

Logs the name of every label in your Gmail account.

GmailApp.GmailLabel

Show example code

Code.gs

function logAllLabelNames() {
  const names = GmailApp.getUserLabels().map((label) => label.getName());
  Logger.log(names.join(', ') || 'No labels');
}

Technical reference

Exact names and signatures

Open method details when you need them.

At a glance

Service: GmailApp
Reference symbol: GmailApp.GmailLabel
Object: GmailLabel
Runtime: From signature data

Open the Google reference source

Methods and signatures

Browse 9 methods

addToThread

From signature data Google source

addToThread(thread: GmailApp.GmailThread): GmailApp.GmailLabel

addToThreads

From signature data Google source

addToThreads(threads: GmailApp.GmailThread[]): GmailApp.GmailLabel

deleteLabel

From signature data Google source

deleteLabel(): void

getId

From signature data Google source

getId(): string

getName

From signature data Google source

getName(): string

getThreads

From signature data Google source

getThreads(): GmailApp.GmailThread[]
getThreads(start: number, max: number): GmailApp.GmailThread[]

getUnreadCount

From signature data Google source

getUnreadCount(): number

removeFromThread

From signature data Google source

removeFromThread(thread: GmailApp.GmailThread): GmailApp.GmailLabel

removeFromThreads

From signature data Google source

removeFromThreads(threads: GmailApp.GmailThread[]): GmailApp.GmailLabel

Need the whole workflow?

Return to a task guide

Task guides cover setup, permissions, expected results, and troubleshooting as well as object methods.

Browse Gmail tasks