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

This counts the conversations tagged with the label and does not change any of them.

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)

This adds the label to the newest matching conversation. It changes that conversation, but it does not delete or send anything.

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

This lists the names of every label in your Gmail account and does not change any of them.

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

Generated runtime and signature facts stay separate from the beginner actions above. Open method details only 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