Google Apps Script

Class GmailThread

A thread in a user's Gmail account.

Methods

MethodReturn typeBrief description
addLabel(label)GmailThreadAdds this label to the thread.
getFirstMessageSubject()StringGets the subject of the first message in the thread.
getId()StringGets the id of this thread.
getLabels()GmailLabel[]Returns the user-created labels on this thread.
getLastMessageDate()DateGets the date of this thread's most recent message.
getMessageCount()IntegerReturns the number of messages in the thread.
getMessages()GmailMessage[]Gets the messages in this thread.
getPermalink()StringGets a permalink for this thread.
hasStarredMessages()BooleanReturns whether the thread has any starred messages.
isImportant()BooleanReturns whether the thread is marked important.
isInChats()BooleanReturns whether the thread is labeled a chat.
isInInbox()BooleanReturns whether the thread is in the inbox.
isInSpam()BooleanReturns whether the thread is marked as spam.
isInTrash()BooleanReturns whether the thread is in the trash.
isUnread()BooleanReturns whether the thread has any unread messages.
markImportant()GmailThreadMarks this thread as important.
markRead()GmailThreadMarks this thread as read.
markUnimportant()GmailThreadMarks this thread as unimportant.
markUnread()GmailThreadMarks this thread as unread.
moveToArchive()GmailThreadMoves this thread to the archive.
moveToInbox()GmailThreadMoves this thread to the inbox.
moveToSpam()GmailThreadMoves this thread to spam.
moveToTrash()GmailThreadMoves this thread to the trash.
refresh()GmailThreadReloads this thread, and associated state from Gmail (useful in case the labels, read state, etc., have changed).
removeLabel(label)GmailThreadRemoves this label from the thread.
reply(body)GmailThreadReply to the sender of the last message on this thread using the replyTo address.
reply(body, options)GmailThreadReply to the sender of the last message on this thread using the replyTo address, with optional arguments.
replyAll(body)GmailThreadReply to the sender (using the replyTo address), and all recipients of the last message on this thread.
replyAll(body, options)GmailThreadReply to the sender (using the replyTo address), and all recipients of the last message on this thread, with optional arguments.

Detailed documentation

addLabel(label)

Adds this label to the thread.

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

Parameters

NameTypeDescription
labelGmailLabelthe label to apply to this thread

Return

GmailThread — this thread, useful for chaining

See also


getFirstMessageSubject()

Gets the subject of the first message in the thread.

 
// log the subject of the first message in the first thread in the inbox
 var firstThread = GmailApp.getInboxThreads(0,1)[0];
 Logger.log(firstThread.getFirstMessageSubject());
 

Return

String — the subject of the first message in the thread

See also


getId()

Gets the id of this thread.

 
// log the subject of the first message in the first thread in the inbox
 var firstThread = GmailApp.getInboxThreads(0,1)[0];
 var id = firstThread.getId();
 // get same thread by its id
 var thread = GmailApp.getThreadById(id);
 Logger.log(thread.getFirstMessageSubject() ==
 firstThread.getFirstMessageSubject()); // will always log true
 

Return

String — the id of this thread


getLabels()

Returns the user-created labels on this thread.

 
// log the names of the labels attached to the first thread in the inbox
 var firstThread = GmailApp.getInboxThreads(0,1)[0];
 var labels = firstThread.getLabels();
 for (var i = 0; i < labels.length; i++) {
   Logger.log(labels[i].getName());
 }
 

Return

GmailLabel[] — an array of labels for this thread


getLastMessageDate()

Gets the date of this thread's most recent message.

 
// log the date of the most recent message on the first thread in the inbox
 var firstThread = GmailApp.getInboxThreads(0,1)[0];
 Logger.log(firstThread.getLastMessageDate());
 

Return

Date — the date of the most recent message in the thread

See also


getMessageCount()

Returns the number of messages in the thread.

 
// log the number of messages in the thread
 var firstThread = GmailApp.getInboxThreads(0,1)[0];
 Logger.log(firstThread.getMessageCount());
 

Return

Integer — the number of messages in the thread

See also


getMessages()

Gets the messages in this thread.

 
// log the subjects of the messages in the thread
 var firstThread = GmailApp.getInboxThreads(0,1)[0];
 var messages = firstThread.getMessages();
 for (var i = 0; i < messages.length; i++) {
   Logger.log(messages[i].getSubject());
 }
 

Return

GmailMessage[] — an array of Gmail messages in this thread

See also


getPermalink()

Gets a permalink for this thread.

 
// Logs the permalink for the first thread in the inbox
 var thread = GmailApp.getInboxThreads(0,1)[0];
 Logger.log(thread.getPermalink());
 

Return

String — the permalink for this thread


hasStarredMessages()

Returns whether the thread has any starred messages.

 
// log if this thread has starred messages
 var firstThread = GmailApp.getInboxThreads(0,1)[0];
 Logger.log('has starred : ' + firstThread.hasStarredMessages());
 

Return

Boolean — true if the thread has any starred messages


isImportant()

Returns whether the thread is marked important.

 
// log if this thread is marked important
 var firstThread = GmailApp.getInboxThreads(0,1)[0];
 Logger.log('Important? : ' + firstThread.isImportant());
 

Return

Boolean — true if the thread is marked important


isInChats()

Returns whether the thread is labeled a chat.

 
// log if this thread is a chat
 var firstThread = GmailApp.getInboxThreads(0,1)[0];
 Logger.log('is in chats? : ' + firstThread.isInChats());
 

Return

Boolean — true if the thread is labeled a chat


isInInbox()

Returns whether the thread is in the inbox.

 
// log if this thread is in the inbox
 var firstThread = GmailApp.getInboxThreads(0,1)[0];
 Logger.log('is in the inbox? : ' + firstThread.isInInbox());
 

Return

Boolean — true if the thread is in the inbox


isInSpam()

Returns whether the thread is marked as spam.

 
// log if this thread is in the spam folder
 var firstThread = GmailApp.getInboxThreads(0,1)[0];
 Logger.log('Spam? ' + firstThread.isInSpam());
 

Return

Boolean — true if the thread is marked as spam


isInTrash()

Returns whether the thread is in the trash.

 
// log if this thread is in the trash
 var firstThread = GmailApp.getInboxThreads(0,1)[0];
 Logger.log('Trashed? ' + firstThread.isInTrash());
 

Return

Boolean — true if the thread is in the trash


isUnread()

Returns whether the thread has any unread messages.

 
// log if this thread is unread
 var firstThread = GmailApp.getInboxThreads(0,1)[0];
 Logger.log('Unread? ' + firstThread.isUnread());
 

Return

Boolean — true if there are unread messages


markImportant()

Marks this thread as important.

 
// mark first inbox thread as important
 var firstThread = GmailApp.getInboxThreads(0,1)[0];
 firstThread.markImportant();
 

Return

GmailThread — this thread, useful for chaining

See also


markRead()

Marks this thread as read.

 
// mark first inbox thread as read
 var firstThread = GmailApp.getInboxThreads(0,1)[0];
 firstThread.markRead();
 

Return

GmailThread — this thread, useful for chaining

See also


markUnimportant()

Marks this thread as unimportant.

 
// mark first inbox thread as unimportant
 var firstThread = GmailApp.getInboxThreads(0,1)[0];
 firstThread.markUnimportant();
 

Return

GmailThread — this thread, useful for chaining

See also


markUnread()

Marks this thread as unread.

 
// mark first inbox thread as unread
 var firstThread = GmailApp.getInboxThreads(0,1)[0];
 firstThread.markUnread();
 

Return

GmailThread — this thread, useful for chaining

See also


moveToArchive()

Moves this thread to the archive.

 
// archive first inbox thread
 var firstThread = GmailApp.getInboxThreads(0,1)[0];
 firstThread.moveToArchive();
 

Return

GmailThread — this thread, useful for chaining


moveToInbox()

Moves this thread to the inbox.

 
// move first non-inbox thread to inbox
 var firstThread = GmailApp.search("-in:inbox")[0];
 firstThread.moveToInbox();
 

Return

GmailThread — this thread, useful for chaining


moveToSpam()

Moves this thread to spam.

 
// move first inbox thread to spam
 var firstThread = GmailApp.getInboxThreads(0,1)[0];
 firstThread.moveToSpam();
 

Return

GmailThread — this thread, useful for chaining


moveToTrash()

Moves this thread to the trash.

 
// move first inbox thread to trash
 var firstThread = GmailApp.getInboxThreads(0,1)[0];
 firstThread.moveToTrash();
 

Return

GmailThread — this thread, useful for chaining


refresh()

Reloads this thread, and associated state from Gmail (useful in case the labels, read state, etc., have changed).

 
var firstThread = GmailApp.getInboxThreads(0,1)[0];
 // ...do something that may take a while here....
 firstThread.refresh(); // make sure it's up-to-date
 // ...do more stuff with firstThread ...
 

Return

GmailThread — this thread, useful for chaining


removeLabel(label)

Removes this label from the thread.

 
var myLabel = GmailApp.getUserLabelByName('<your label>');
 var threads = myLabel.getThreads();
 for (var x in threads) {
   var thread = threads[x];
   thread.removeLabel(myLabel);
 }
 

Parameters

NameTypeDescription
labelGmailLabelthe label to remove from this thread

Return

GmailThread — this thread, useful for chaining

See also


reply(body)

Reply to the sender of the last message on this thread using the replyTo address. Note that the total size of the email (including all headers) may not exceed 20KB.

 
// respond to author of last email in thread with acknowledgment
 var firstThread = GmailApp.getInboxThreads(0,1)[0];
 firstThread.reply("Got your message");
 

Parameters

NameTypeDescription
bodyStringthe body of the email

Return

GmailThread — this thread, useful for chaining

See also


reply(body, options)

Reply to the sender of the last message on this thread using the replyTo address, with optional arguments. The email can contain both plain text, and also a html body. Note that the total size of the email (including all headers, but excluding attachments) may not exceed 20KB.

 
// respond with html body text
 var firstThread = GmailApp.getInboxThreads(0,1)[0];
 firstThread.reply("incapable of html", {
   htmlBody: "some html body text",
   noReply: true
 });
 

Parameters

NameTypeDescription
bodyStringthe body of the email
optionsObjecta JavaScript object that specifies advanced parameters, as listed below

Advanced parameters

NameTypeDescription
ccStringa comma separated list of email addresses to CC
bccStringa comma separated list of email addresses to BCC
htmlBodyStringif set, devices capable of rendering HTML will use it instead of the required body argument; you can add an optional inlineImages field in HTML body if you have inlined images for your email
nameStringthe name of the sender of the email (default: the user's name)
fromStringthe address that the email should be sent from, which must be one of the values returned by GmailApp.getAliases()
replyToStringan email address to use as the default reply-to address (default: the user's email address)
noReplyBooleantrue if the email should be sent from a generic no-reply email address to discourage recipients from responding to emails; this option is only possible for Google Apps accounts, not Gmail users
attachmentsBlobSource[]an array of files to send with the email
inlineImagesObjecta JavaScript object containing a mapping from image key (String) to image data (BlobSource); this assumes that the htmlBody parameter is used and contains references to these images in the format <img src="cid:imageKey" />

Return

GmailThread — this thread, useful for chaining

See also


replyAll(body)

Reply to the sender (using the replyTo address), and all recipients of the last message on this thread. Note that the total size of the email (including all headers) may not exceed 20KB.

 
// respond to all with acknowledgment to the first thread in the inbox
 var firstThread = GmailApp.getInboxThreads(0,1)[0];
 firstThread.replyAll("Got your message");
 

Parameters

NameTypeDescription
bodyStringthe body of the email

Return

GmailThread — this thread, useful for chaining

See also


replyAll(body, options)

Reply to the sender (using the replyTo address), and all recipients of the last message on this thread, with optional arguments. The email can contain both plain text, and also a html body. Note that the total size of the email (including all headers, but excluding attachments) may not exceed 20KB.

 
// respond with html body text
 var firstThread = GmailApp.getInboxThreads(0,1)[0];
 firstThread.replyAll("incapable of html", {
   htmlBody: "some html body text",
   noReply: true
 });
 

Parameters

NameTypeDescription
bodyStringthe body of the email
optionsObjecta JavaScript object that specifies advanced parameters, as listed below

Advanced parameters

NameTypeDescription
ccStringa comma separated list of email addresses to CC
bccStringa comma separated list of email addresses to BCC
htmlBodyStringif set, devices capable of rendering HTML will use it instead of the required body argument; you can add an optional inlineImages field in HTML body if you have inlined images for your email
nameStringthe name of the sender of the email (default: the user's name)
fromStringthe address that the email should be sent from, which must be one of the values returned by GmailApp.getAliases()
replyToStringan email address to use as the default reply-to address (default: the user's email address)
noReplyBooleantrue if the email should be sent from a generic no-reply email address to discourage recipients from responding to emails; this option is only possible for Google Apps accounts, not Gmail users
attachmentsBlobSource[]an array of files to send with the email
inlineImagesObjecta JavaScript object containing a mapping from image key (String) to image data (BlobSource); this assumes that the htmlBody parameter is used and contains references to these images in the format <img src="cid:imageKey" />

Return

GmailThread — this thread, useful for chaining

See also

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.