Skip to content

Object reference

Gmail thread

A GmailThread holds one Gmail conversation. Reach threads with GmailApp.search() or label.getThreads(), then call getMessages() or addLabel().

GmailApp.GmailThread

Start here

Get this object first

Get threads from a Gmail label with label.getThreads(), or search your mailbox directly with GmailApp.search(query, start, max).

Code.gs 
function showFirstLabeledThreadSubject() {
  const label = GmailApp.getUserLabelByName('Save to Drive');
  if (!label) throw new Error('Create a Gmail label named Save to Drive first.');
  const threads = label.getThreads();
  if (!threads.length) return;
  Logger.log(threads[0].getFirstMessageSubject());
}

Then use it

Common actions

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

Count the messages in a conversation

This records a count for the first conversation carrying your Save to Drive label.

GmailApp.GmailThread
Show example code
Code.gs 
function countFirstLabeledThreadMessages() {
  const label = GmailApp.getUserLabelByName('Save to Drive');
  if (!label) throw new Error('Create a Gmail label named Save to Drive first.');
  const threads = label.getThreads();
  if (!threads.length) return;
  Logger.log(threads[0].getMessages().length);
}

Search recent threads and log subjects

This searches the last 7 days with GmailApp.search() and logs up to 5 thread subjects and message counts without changing any mail.

GmailApp.GmailThread
Show example code
Code.gs 
function logRecentThreadSubjects() {
  const threads = GmailApp.search('newer_than:7d', 0, 5);
  threads.forEach((thread) => {
    Logger.log(thread.getFirstMessageSubject() + ' (' + thread.getMessageCount() + ' messages)');
  });
}

List user labels on a conversation

This reads getLabels() on the first matching thread and logs the label names without adding or removing any labels.

GmailApp.GmailThreadGmailApp.GmailLabel
Show example code
Code.gs 
function logThreadLabelNames() {
  const label = GmailApp.getUserLabelByName('Save to Drive');
  if (!label) throw new Error('Create a Gmail label named Save to Drive first.');
  const threads = label.getThreads();
  if (!threads.length) return;
  const labelNames = threads[0].getLabels().map((item) => item.getName());
  Logger.log(labelNames.join(', '));
}

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.GmailThread
Object
GmailThread
Runtime
From signature data

Open the Google reference source

Methods and signatures

Browse 30 methods

addLabel

From signature data Google source
  • addLabel(label: GmailApp.GmailLabel): GmailApp.GmailThread

createDraftReply

From signature data Google source
  • createDraftReply(body: string): GmailApp.GmailDraft
  • createDraftReply(body: string, options: unknown): GmailApp.GmailDraft

createDraftReplyAll

From signature data Google source
  • createDraftReplyAll(body: string): GmailApp.GmailDraft
  • createDraftReplyAll(body: string, options: unknown): GmailApp.GmailDraft

getFirstMessageSubject

From signature data Google source
  • getFirstMessageSubject(): string

getId

From signature data Google source
  • getId(): string

getLabels

From signature data Google source
  • getLabels(): GmailApp.GmailLabel[]

getLastMessageDate

From signature data Google source
  • getLastMessageDate(): Date

getMessageCount

From signature data Google source
  • getMessageCount(): number

getMessages

From signature data Google source
  • getMessages(): GmailApp.GmailMessage[]
From signature data Google source
  • getPermalink(): string

hasStarredMessages

From signature data Google source
  • hasStarredMessages(): boolean

isImportant

From signature data Google source
  • isImportant(): boolean

isInChats

From signature data Google source
  • isInChats(): boolean

isInInbox

From signature data Google source
  • isInInbox(): boolean

isInPriorityInbox

From signature data Google source
  • isInPriorityInbox(): boolean

isInSpam

From signature data Google source
  • isInSpam(): boolean

isInTrash

From signature data Google source
  • isInTrash(): boolean

isUnread

From signature data Google source
  • isUnread(): boolean

markImportant

From signature data Google source
  • markImportant(): GmailApp.GmailThread

markRead

From signature data Google source
  • markRead(): GmailApp.GmailThread

markUnimportant

From signature data Google source
  • markUnimportant(): GmailApp.GmailThread

markUnread

From signature data Google source
  • markUnread(): GmailApp.GmailThread

moveToArchive

From signature data Google source
  • moveToArchive(): GmailApp.GmailThread

moveToInbox

From signature data Google source
  • moveToInbox(): GmailApp.GmailThread

moveToSpam

From signature data Google source
  • moveToSpam(): GmailApp.GmailThread

moveToTrash

From signature data Google source
  • moveToTrash(): GmailApp.GmailThread

refresh

From signature data Google source
  • refresh(): GmailApp.GmailThread

removeLabel

From signature data Google source
  • removeLabel(label: GmailApp.GmailLabel): GmailApp.GmailThread

reply

From signature data Google source
  • reply(body: string): GmailApp.GmailThread
  • reply(body: string, options: GmailApp.GmailAdvancedParameters): GmailApp.GmailThread

replyAll

From signature data Google source
  • replyAll(body: string): GmailApp.GmailThread
  • replyAll(body: string, options: unknown): GmailApp.GmailThread

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