Google Apps Script

Class GmailApp

Provides access to Gmail threads, messages, and labels.

Methods

MethodReturn typeBrief description
createLabel(name)GmailLabelCreate a new user label of the given name.
deleteLabel(label)GmailAppDeletes the specified label.
getAliases()String[]Gets a list of the emails that are set up as aliases for this account in Gmail.
getChatThreads()GmailThread[]Retrieves all chat threads irrespective of labels.
getChatThreads(start, max)GmailThread[]Retrieves a range of chat threads irrespective of labels.
getDraftMessages()GmailMessage[]Retrieves all draft messages.
getInboxThreads()GmailThread[]Retrieves all Inbox threads irrespective of labels.
getInboxThreads(start, max)GmailThread[]Retrieves a range of Inbox threads irrespective of labels.
getInboxUnreadCount()IntegerGets the number of unread threads in the inbox.
getMessageById(id)GmailMessageGets a message by id.
getMessagesForThread(thread)GmailMessage[]Retrieve all messages in the specified thread.
getMessagesForThreads(threads)GmailMessage[][]Retrieve all messages in the specified threads.
getPriorityInboxThreads()GmailThread[]Retrieves all Priority Inbox threads irrespective of labels.
getPriorityInboxThreads(start, max)GmailThread[]Retrieves a range of Priority Inbox threads irrespective of labels.
getPriorityInboxUnreadCount()IntegerGets the number of unread threads in the Priority Inbox.
getSpamThreads()GmailThread[]Retrieves all spam threads irrespective of labels.
getSpamThreads(start, max)GmailThread[]Retrieves a range of spam threads irrespective of labels.
getSpamUnreadCount()IntegerGets the number of unread threads that are spam.
getStarredThreads()GmailThread[]Retrieves all starred threads irrespective of labels.
getStarredThreads(start, max)GmailThread[]Retrieves a range of starred threads irrespective of labels.
getStarredUnreadCount()IntegerGets the number of unread threads that are starred.
getThreadById(id)GmailThreadGets a thread by id.
getTrashThreads()GmailThread[]Retrieves all trash threads irrespective of labels.
getTrashThreads(start, max)GmailThread[]Retrieves a range of trash threads irrespective of labels.
getUserLabelByName(name)GmailLabelRetrieves a label given the label name.
getUserLabels()GmailLabel[]Retrieves a list of user-created labels.
markMessageRead(message)GmailAppMarks this message read and forces the message to refresh.
markMessageUnread(message)GmailAppMarks this message unread and forces the message to refresh.
markMessagesRead(messages)GmailAppMarks these messages read and forces the messages to refresh.
markMessagesUnread(messages)GmailAppMarks these messages unread and forces the messages to refresh.
markThreadImportant(thread)GmailAppMarks this thread as important and forces the thread to refresh.
markThreadRead(thread)GmailAppMarks this thread as read and forces the thread to refresh.
markThreadUnimportant(thread)GmailAppMarks this thread as unimportant and forces the thread to refresh.
markThreadUnread(thread)GmailAppMarks this thread unread and forces the thread to refresh.
markThreadsImportant(threads)GmailAppMarks these threads as important and forces the threads to refresh.
markThreadsRead(threads)GmailAppMarks these threads as read and forces the threads to refresh.
markThreadsUnimportant(threads)GmailAppMarks these threads as unimportant and forces the threads to refresh.
markThreadsUnread(threads)GmailAppMarks these threads as unread and forces the threads to refresh.
moveMessageToTrash(message)GmailAppMoves the message to the trash and forces the message to refresh.
moveMessagesToTrash(messages)GmailAppMoves the specified messages to the trash and forces the messages to refresh.
moveThreadToArchive(thread)GmailAppMoves this thread to the archive and forces the thread to refresh.
moveThreadToInbox(thread)GmailAppMoves this thread to the inbox and forces the thread to refresh.
moveThreadToSpam(thread)GmailAppMoves this thread to spam and forces the thread to refresh.
moveThreadToTrash(thread)GmailAppMoves this thread to the trash and forces the thread to refresh.
moveThreadsToArchive(threads)GmailAppMoves these threads to the archive and forces the threads to refresh.
moveThreadsToInbox(threads)GmailAppMoves these threads to the inbox and forces the threads to refresh.
moveThreadsToSpam(threads)GmailAppMoves these threads to spam and forces the threads to refresh.
moveThreadsToTrash(threads)GmailAppMoves these threads to the trash and forces the threads to refresh.
refreshMessage(message)GmailAppReloads the message and associated state from Gmail (useful in case the labels, read state, etc., have changed).
refreshMessages(messages)GmailAppReloads the messages and associated state from Gmail (useful in case the labels, read state, etc., have changed).
refreshThread(thread)GmailAppReloads the thread and associated state from Gmail (useful in case the labels, read state, etc., have changed).
refreshThreads(threads)GmailAppReloads the threads and associated state from Gmail (useful in case the labels, read state, etc., have changed).
search(query)GmailThread[]Search Gmail with the given query.
search(query, start, max)GmailThread[]Search Gmail with the given query.
sendEmail(recipient, subject, body)GmailAppSends an email message.
sendEmail(recipient, subject, body, options)GmailAppSends an email message with optional arguments.
starMessage(message)GmailAppAdds a star to this message and forces the message to refresh.
starMessages(messages)GmailAppAdds stars to these messages and forces the messages to refresh.
unstarMessage(message)GmailAppRemoves a star from this message and forces the message to refresh.
unstarMessages(messages)GmailAppRemoves stars from these messages and forces the messages to refresh.

Detailed documentation

createLabel(name)

Create a new user label of the given name.

 
// creates the label @FOO and logs label: FOO
 Logger.log("label: " + GmailApp.createLabel("FOO"));
 

Parameters

NameTypeDescription
nameStringthe name of the new label

Return

GmailLabel — the newly created label

See also


deleteLabel(label)

Deletes the specified label.

 
// have to get the label by name first
 var label = GmailApp.getUserLabelByName("FOO");
 GmailApp.deleteLabel(label);
 

Parameters

NameTypeDescription
labelGmailLabelthe label to delete

Return

GmailApp — the Gmail service, useful for chaining

See also


getAliases()

Gets a list of the emails that are set up as aliases for this account in Gmail. You can send a message from any of these aliases by using the "from" optional argument.

 // Log the aliases for this Gmail account and send an email as the first one.
 var me = Session.getActiveUser().getEmail();
 var aliases = GmailApp.getAliases();
 Logger.log(aliases);
 if (aliases.length > 0) {
   GmailApp.sendEmail(me, 'From an alias', 'A message from an alias!', {'from': aliases[0]});
 } else {
   GmailApp.sendEmail(me, 'No aliases found', 'You have no aliases.');
 }
 

Return

String[] — an array of aliases for this account

See also


getChatThreads()

Retrieves all chat threads irrespective of labels. This call will fail when the size of all threads is too large for the system to handle. Where the thread size is unknown, and potentially very large, please use the 'paged' call, and specify ranges of the threads to retrieve in each call.

 
var threads = GmailApp.getChatThreads();
 Logger.log("# of chat threads: " + threads.length);
 

Return

GmailThread[] — an array of chat Gmail threads


getChatThreads(start, max)

Retrieves a range of chat threads irrespective of labels.

 
// get first 50 chat threads
 var threads = GmailApp.getChatThreads(0,50);
 // will log no more than 50.0
 Logger.log(threads.length);
 Logger.log(threads[0].getFirstMessageSubject());
 

Parameters

NameTypeDescription
startIntegerthe index of the first thread to retrieve
maxIntegerthe maximum number of threads to retrieve

Return

GmailThread[] — an array of chat Gmail threads


getDraftMessages()

Retrieves all draft messages.

 
// Logs the number of draft messages
 var drafts = GmailApp.getDraftMessages();
 Logger.log(drafts.length);
 

Return

GmailMessage[] — an array of draft Gmail messages


getInboxThreads()

Retrieves all Inbox threads irrespective of labels. This call will fail when the size of all threads is too large for the system to handle. Where the thread size is unknown, and potentially very large, please use the 'paged' call, and specify ranges of the threads to retrieve in each call.

 
// Log the subject lines of your Inbox
 var threads = GmailApp.getInboxThreads();
 for (var i = 0; i < threads.length; i++) {
   Logger.log(threads[i].getFirstMessageSubject());
 }
 

Return

GmailThread[] — an array of Gmail threads in the Inbox


getInboxThreads(start, max)

Retrieves a range of Inbox threads irrespective of labels.

 
// Log the subject lines of up to the first 50 emails in your Inbox
 var threads = GmailApp.getInboxThreads(0, 50);
 for (var i = 0; i < threads.length; i++) {
   Logger.log(threads[i].getFirstMessageSubject());
 }
 

Parameters

NameTypeDescription
startIntegerthe index of the first thread to retrieve
maxIntegerthe maximum number of threads to retrieve

Return

GmailThread[] — an array of Gmail threads in the Inbox


getInboxUnreadCount()

Gets the number of unread threads in the inbox.

 
Logger.log("Messages unread in inbox: " + GmailApp.getInboxUnreadCount());
 

Return

Integer — the number of threads in the inbox that have unread messages


getMessageById(id)

Gets a message by id. Use this in conjunction with getId() on Gmail messages.

 
// get the first message in the first thread of your inbox
 var message = GmailApp.getInboxThreads(0, 1)[0].getMessages()[0];
 // get its id
 var messageId = message.getId();
 // now fetch the same message by that id
 var messageById = GmailApp.getMessageById(messageId);
 // should always log true as they should be the same message
 Logger.log(message.getSubject() == messageById.getSubject());
 

Parameters

NameTypeDescription
idStringthe id of the message to retrieve

Return

GmailMessage — the message with the given id or null if not found

See also


getMessagesForThread(thread)

Retrieve all messages in the specified thread.

 
// Log all the subject lines in the first thread of your inbox
 var thread = GmailApp.getInboxThreads(0, 1)[0];
 var messages = GmailApp.getMessagesForThread(thread);
 for (var i = 0 ; i < messages.length; i++) {
   Logger.log("subject: " + messages[i].getSubject());
 }
 

Parameters

NameTypeDescription
threadGmailThreadthe thread of messages to retrieve

Return

GmailMessage[] — array of messages corresponding to this thread

See also


getMessagesForThreads(threads)

Retrieve all messages in the specified threads.

 
// Log the subject lines of all messages in the first two threads of your inbox
 var thread = GmailApp.getInboxThreads(0, 2);
 var messages = GmailApp.getMessagesForThreads(thread);
 for (var i = 0 ; i < messages.length; i++) {
   for (var j = 0; j < messages[i].length; j++) {
     Logger.log("subject: " + messages[i][j].getSubject());
   }
 }
 

Parameters

NameTypeDescription
threadsGmailThread[]the threads of messages to retrieve

Return

GmailMessage[][] — an array of arrays of messages, where each item in the outer array corresponds to a thread and the inner array contains the messages in that thread

See also


getPriorityInboxThreads()

Retrieves all Priority Inbox threads irrespective of labels. This call will fail when the size of all threads is too large for the system to handle. Where the thread size is unknown, and potentially very large, please use the 'paged' call, and specify ranges of the threads to retrieve in each call.

 
Logger.log("# of messages in your Priority Inbox: " +
            GmailApp.getPriorityInboxThreads().length);
 

Return

GmailThread[] — an array of Gmail threads in the Priority Inbox


getPriorityInboxThreads(start, max)

Retrieves a range of Priority Inbox threads irrespective of labels.

 
// will log some number 2 or less
 Logger.log("# of messages in your Priority Inbox: " +
            GmailApp.getPriorityInboxThreads(0, 2).length);
 

Parameters

NameTypeDescription
startIntegerthe index of the first thread to retrieve
maxIntegerthe maximum number of threads to retrieve

Return

GmailThread[] — an array of Gmail threads in the Priority Inbox


getPriorityInboxUnreadCount()

Gets the number of unread threads in the Priority Inbox.

 
Logger.log("Number of unread emails in your Priority Inbox : " +
            GmailApp.getPriorityInboxUnreadCount());
 

Return

Integer — the number of threads in the Priority Inbox that have unread messages


getSpamThreads()

Retrieves all spam threads irrespective of labels. This call will fail when the size of all threads is too large for the system to handle. Where the thread size is unknown, and potentially very large, please use the 'paged' call, and specify ranges of the threads to retrieve in each call.

 
Logger.log("# of total spam threads: " + GmailApp.getSpamThreads().length);
 

Return

GmailThread[] — an array of Gmail threads in the spam folder


getSpamThreads(start, max)

Retrieves a range of spam threads irrespective of labels.

 
// will log a number at most 5
 Logger.log("# of total spam threads: " + GmailApp.getSpamThreads(0, 5).length);
 

Parameters

NameTypeDescription
startIntegerthe index of the first thread to retrieve
maxIntegerthe maximum number of threads to retrieve

Return

GmailThread[] — an array of Gmail threads in the spam folder


getSpamUnreadCount()

Gets the number of unread threads that are spam.

 
// Unless you actually read stuff in your spam folder, this should be the same as
 // the number of messages in your spam folder.
 Logger.log("# unread threads that are spam: " + GmailApp.getSpamUnreadCount());
 

Return

Integer — the number spam threads that have unread messages


getStarredThreads()

Retrieves all starred threads irrespective of labels. This call will fail when the size of all threads is too large for the system to handle. Where the thread size is unknown, and potentially very large, please use the 'paged' call, and specify ranges of the threads to retrieve in each call.

 
// logs the number of starred threads
 Logger.log("# Starred threads: " + GmailApp.getStarredThreads().length);
 

Return

GmailThread[] — an array of starred Gmail threads


getStarredThreads(start, max)

Retrieves a range of starred threads irrespective of labels.

 
// logs the number of starred threads to a maximum of 5
 Logger.log("# Starred threads: " + GmailApp.getStarredThreads(0, 5).length);
 

Parameters

NameTypeDescription
startIntegerthe index of the first thread to retrieve
maxIntegerthe maximum number of threads to retrieve

Return

GmailThread[] — an array of starred Gmail threads


getStarredUnreadCount()

Gets the number of unread threads that are starred.

 
Logger.log("# unread and starred: " + GmailApp.getStarredUnreadCount());
 

Return

Integer — the number of starred threads that have unread messages


getThreadById(id)

Gets a thread by id. Use this in conjunction with getId() on Gmail threads.

 
// thread ids can also be found in the location bar when you have a thread open in Gmail
 // get first inbox thread
 var firstThread = GmailApp.getInboxThreads(0,1)[0];
 // get the same thread by id
 var threadById = GmailApp.getThreadById(firstThread.getId());
 // verify they are the same
 Logger.log(firstThread.getFirstMessageSubject() == threadById.getFirstMessageSubject());
 

Parameters

NameTypeDescription
idStringthe ide of the thread to retrieve

Return

GmailThread — the thread with the given id or null if not found

See also


getTrashThreads()

Retrieves all trash threads irrespective of labels. This call will fail when the size of all threads is too large for the system to handle. Where the thread size is unknown, and potentially very large, please use the 'paged' call, and specify ranges of the threads to retrieve in each call.

 
Logger.log("# of total trash threads: " + GmailApp.getTrashThreads().length);
 

Return

GmailThread[] — an array of Gmail threads in the trash


getTrashThreads(start, max)

Retrieves a range of trash threads irrespective of labels.

 
// will log a number at most 5
 Logger.log("# of total trash threads: " + GmailApp.getTrashThreads(0, 5).length);
 

Parameters

NameTypeDescription
startIntegerthe index of the first thread to retrieve
maxIntegerthe maximum number of threads to retrieve

Return

GmailThread[] — an array of Gmail threads in the trash


getUserLabelByName(name)

Retrieves a label given the label name.

 
var labelObject = GmailApp.getUserLabelByName("myLabel");
 

Parameters

NameTypeDescription
nameStringthe name of the label to retrieve

Return

GmailLabel — the Gmail label with the given name


getUserLabels()

Retrieves a list of user-created labels.

 
// logs all of the names of your labels
 var labels = GmailApp.getUserLabels();
 for (var i = 0; i < labels.length; i++) {
   Logger.log("label: " + labels[i].getName());
 }
 

Return

GmailLabel[] — array of user created labels


markMessageRead(message)

Marks this message read and forces the message to refresh.

 
// mark the first message in the first thread of your inbox as read
 var message = GmailApp.getInboxThreads(0, 1)[0].getMessages()[0];
 GmailApp.markMessageRead(message);
 

Parameters

NameTypeDescription
messageGmailMessagethe message to mark as read

Return

GmailApp — the Gmail service, useful for chaining

See also


markMessageUnread(message)

Marks this message unread and forces the message to refresh.

 
// mark the first message in the first thread of your inbox as unread
 var message = GmailApp.getInboxThreads(0, 1)[0].getMessages()[0];
 GmailApp.markMessageUnread(message);
 

Parameters

NameTypeDescription
messageGmailMessagethe message to mark as unread

Return

GmailApp — the Gmail service, useful for chaining

See also


markMessagesRead(messages)

Marks these messages read and forces the messages to refresh.

 
// mark first three messages in the first inbox thread as read
 // assumes that the first inbox thread has 3 messages in it
 var threadMessages = GmailApp.getInboxThreads(0, 1)[0].getMessages();
 var messages = [threadMessages[0], threadMessages[1], threadMessages[2]];
 GmailApp.markMessagesRead(thread.getMessages());
 

Parameters

NameTypeDescription
messagesGmailMessage[]an array of messages to mark as read

Return

GmailApp — the Gmail service, useful for chaining

See also


markMessagesUnread(messages)

Marks these messages unread and forces the messages to refresh.

 
// mark first three messages in the first inbox thread as unread
 // assumes that the first inbox thread has 3 messages in it
 var threadMessages = GmailApp.getInboxThreads(0, 1)[0].getMessages();
 var messages = [threadMessages[0], threadMessages[1], threadMessages[2]];
 GmailApp.markMessagesUnread(thread.getMessages());
 

Parameters

NameTypeDescription
messagesGmailMessage[]an array of messages to mark as unread

Return

GmailApp — the Gmail service, useful for chaining

See also


markThreadImportant(thread)

Marks this thread as important and forces the thread to refresh.

 
// marks first inbox thread as important
 var thread = GmailApp.getInboxThreads(0, 1)[0];
 GmailApp.markThreadImportant(thread);
 

Parameters

NameTypeDescription
threadGmailThreadthe thread to mark as important

Return

GmailApp — the Gmail service, useful for chaining

See also


markThreadRead(thread)

Marks this thread as read and forces the thread to refresh.

 
// marks first inbox thread as read
 var thread = GmailApp.getInboxThreads(0, 1)[0];
 GmailApp.markThreadRead(thread);
 

Parameters

NameTypeDescription
threadGmailThreadthe thread to mark as read

Return

GmailApp — the Gmail service, useful for chaining

See also


markThreadUnimportant(thread)

Marks this thread as unimportant and forces the thread to refresh.

 
// marks first inbox thread as unimportant
 var thread = GmailApp.getInboxThreads(0, 1)[0];
 GmailApp.markThreadUnimportant(thread);
 

Parameters

NameTypeDescription
threadGmailThreadthe thread to mark as unimportant

Return

GmailApp — the Gmail service, useful for chaining

See also


markThreadUnread(thread)

Marks this thread unread and forces the thread to refresh.

 
// marks first inbox thread as unread
 var thread = GmailApp.getInboxThreads(0, 1)[0];
 GmailApp.markThreadUnread(thread);
 

Parameters

NameTypeDescription
threadGmailThreadthe thread to mark as unread

Return

GmailApp — the Gmail service, useful for chaining

See also


markThreadsImportant(threads)

Marks these threads as important and forces the threads to refresh.

 
// Marks first two threads in inbox as important
 var threads = GmailApp.getInboxThreads(0, 2);
 GmailApp.markThreadsImportant(threads);
 

Parameters

NameTypeDescription
threadsGmailThread[]an array of threads to mark as important

Return

GmailApp — the Gmail service, useful for chaining

See also


markThreadsRead(threads)

Marks these threads as read and forces the threads to refresh.

 
// Marks first two threads in inbox as read
 var threads = GmailApp.getInboxThreads(0, 2);
 GmailApp.markThreadsRead(threads);
 

Parameters

NameTypeDescription
threadsGmailThread[]an array of threads to mark as read

Return

GmailApp — the Gmail service, useful for chaining

See also


markThreadsUnimportant(threads)

Marks these threads as unimportant and forces the threads to refresh.

 
// Marks first two threads in inbox as unimportant
 var threads = GmailApp.getInboxThreads(0, 2);
 GmailApp.markThreadsUnimportant(threads);
 

Parameters

NameTypeDescription
threadsGmailThread[]an array of threads to mark as unimportant

Return

GmailApp — the Gmail service, useful for chaining

See also


markThreadsUnread(threads)

Marks these threads as unread and forces the threads to refresh.

 
// Marks first two threads in inbox as unread
 var threads = GmailApp.getInboxThreads(0, 2);
 GmailApp.markThreadsUnread(threads);
 

Parameters

NameTypeDescription
threadsGmailThread[]an array of threads to mark as unread

Return

GmailApp — the Gmail service, useful for chaining

See also


moveMessageToTrash(message)

Moves the message to the trash and forces the message to refresh.

 
// move the first message in your inbox to trash
 var firstThread = GmailApp.getInboxThreads(0,1)[0];
 var firstMessage = firstThread.getMessages()[0];
 GmailApp.moveMessageToTrash(firstMessage);
 

Parameters

NameTypeDescription
messageGmailMessagethe message to be trashed

Return

GmailApp — the Gmail service (useful for chaining)

See also


moveMessagesToTrash(messages)

Moves the specified messages to the trash and forces the messages to refresh.

 
// move first two messages in your inbox to trash
 var firstThread = GmailApp.getInboxThreads(0,1)[0];
 var messages = firstThread.getMessages();
 var toDelete = [messages[0], messages[1]];
 GmailApp.moveMessagesToTrash(toDelete);
 

Parameters

NameTypeDescription
messagesGmailMessage[]the messages to be trashed

Return

GmailApp — the Gmail service (useful for chaining)

See also


moveThreadToArchive(thread)

Moves this thread to the archive and forces the thread to refresh.

 
// archive the first thread in your inbox
 var firstThread = GmailApp.getInboxThreads(0,1)[0];
 GmailApp.moveThreadToArchive(firstThread);
 

Parameters

NameTypeDescription
threadGmailThreadthe thread to be archive

Return

GmailApp — the Gmail service, useful for chaining

See also


moveThreadToInbox(thread)

Moves this thread to the inbox and forces the thread to refresh.

 
// find a thread not already in your inbox
 var thread = GmailApp.search("-in:inbox")[0]; // get the first one
 GmailApp.moveThreadToInbox(thread);
 

Parameters

NameTypeDescription
threadGmailThreadthe thread to be moved to the inbox

Return

GmailApp — the Gmail service, useful for chaining

See also


moveThreadToSpam(thread)

Moves this thread to spam and forces the thread to refresh.

 
// tag first thread in inbox as spam
 var firstThread = GmailApp.getInboxThreads(0,1)[0];
 GmailApp.moveThreadToSpam(firstThread);
 

Parameters

NameTypeDescription
threadGmailThreadthe thread to be moved to spam

Return

GmailApp — the Gmail service, useful for chaining

See also


moveThreadToTrash(thread)

Moves this thread to the trash and forces the thread to refresh.

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

Parameters

NameTypeDescription
threadGmailThreadthe thread to be trashed

Return

GmailApp — the Gmail service, useful for chaining

See also


moveThreadsToArchive(threads)

Moves these threads to the archive and forces the threads to refresh.

 
// move first two threads in your inbox to the archive
 var firstTwoThreads = GmailApp.getInboxThreads(0,2);
 GmailApp.moveThreadsToArchive(firstTwoThreads);
 

Parameters

NameTypeDescription
threadsGmailThread[]an array of threads to be archived

Return

GmailApp — the Gmail service, useful for chaining

See also


moveThreadsToInbox(threads)

Moves these threads to the inbox and forces the threads to refresh.

 
// find two threads not already in your inbox
 var firstTwoThreads = GmailApp.search("-in:inbox", 0, 2);
 GmailApp.moveThreadsToInbox(firstTwoThreads);
 

Parameters

NameTypeDescription
threadsGmailThread[]an array of threads to be moved to the inbox

Return

GmailApp — the Gmail service, useful for chaining

See also


moveThreadsToSpam(threads)

Moves these threads to spam and forces the threads to refresh.

 
// move first two threads in your inbox to spam
 var firstTwoThreads = GmailApp.getInboxThreads(0,2);
 GmailApp.moveThreadsToSpam(firstTwoThreads);
 

Parameters

NameTypeDescription
threadsGmailThread[]an array of threads to be moved to spam

Return

GmailApp — the Gmail service, useful for chaining

See also


moveThreadsToTrash(threads)

Moves these threads to the trash and forces the threads to refresh.

 
// move first two threads in your inbox to trash
 var firstTwoThreads = GmailApp.getInboxThreads(0,2);
 GmailApp.moveThreadsToTrash(firstTwoThreads);
 

Parameters

NameTypeDescription
threadsGmailThread[]an array of threads to be trashed

Return

GmailApp — the Gmail service, useful for chaining

See also


refreshMessage(message)

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

 
var firstThread = GmailApp.getInboxThreads(0,1)[0];
 var firstMessage = firstThread.getMessages()[0];
 // ...do something that may take a while here....
 GmailApp.refreshMessage(firstMessage);
 // ...do more stuff with firstMessage...
 

Parameters

NameTypeDescription
messageGmailMessagethe message to be refreshed

Return

GmailApp — the Gmail service, useful for chaining

See also


refreshMessages(messages)

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

 
var firstThread = GmailApp.getInboxThreads(0,1)[0];
 var coupleOfMessages = firstThread.getMessages().slice(0, 2);
 // ...do something that may take a while here....
 GmailApp.refreshMessages(coupleOfMessages);
 // ...do more stuff with coupleOfMessages...
 

Parameters

NameTypeDescription
messagesGmailMessage[]the messages to be refreshed

Return

GmailApp — the Gmail service, useful for chaining

See also


refreshThread(thread)

Reloads the 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....
 GmailApp.refreshThread(firstThread);
 // ... do more stuff with the thread ...
 

Parameters

NameTypeDescription
threadGmailThreadthe thread to be refreshed

Return

GmailApp — the Gmail service, useful for chaining

See also


refreshThreads(threads)

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

 
var threads = GmailApp.getInboxThreads(0, 3);
 // ...do something that may take a while here....
 GmailApp.refreshThreads(threads);
 // ... do more stuff with threads ...
 

Parameters

NameTypeDescription
threadsGmailThread[]the threads to be refreshed

Return

GmailApp — the Gmail service, useful for chaining

See also


search(query)

Search Gmail with the given query. This call will fail when the size of all threads is too large for the system to handle. Where the thread size is unknown, and potentially very large, please use the 'paged' call, and specify ranges of the threads to retrieve in each call.

 
// find starred messages with subject IMPORTANT
 var threads = GmailApp.search('is:starred subject:"IMPORTANT"');
 

Parameters

NameTypeDescription
queryStringthe search query, as you would type it into Gmail

Return

GmailThread[] — an array of Gmail threads matching this query


search(query, start, max)

Search Gmail with the given query.

 
// find starred messages with subject IMPORTANT and return second batch of 10
 // assumes there are at least 11 of them, otherwise this will return an empty array.
 var threads = GmailApp.search('is:starred subject:"IMPORTANT"', 10, 10);
 

Parameters

NameTypeDescription
queryStringthe search query, as you would type it into Gmail
startIntegerthe index of the starting thread
maxIntegerthe maximum number of threads to return

Return

GmailThread[] — an array of Gmail threads matching this query


sendEmail(recipient, subject, body)

Sends an email message. The size of the email (including headers) may not exceed 20KB.

 
// The code below will send an email with the current date an time
 var now = new Date();
 GmailApp.sendEmail("mikemike@gmail.com", "current time", "The time is: " + now.toString());
 

Parameters

NameTypeDescription
recipientStringcomma separated list of email addresses
subjectStringsubject of the email
bodyStringbody of the email

Return

GmailApp — the Gmail service, useful for chaining

See also


sendEmail(recipient, subject, body, options)

Sends an email message with optional arguments. The email can contain plain text or an HTML body. The size of the email (including headers, but excluding attachments) may not exceed 20KB.

 
// Send an email with a file from Google Drive attached as a PDF.
 var file = DriveApp.getFileById('1234567890abcdefghijklmnopqrstuvwxyz');
 GmailApp.sendEmail('mike@example.com', 'Attachment example', 'Please see the attached file.', {
     attachments: [file.getAs(MimeType.PDF)],
     name: 'Automatic Emailer Script'
 });
 

Parameters

NameTypeDescription
recipientStringthe addresses of the recipient
subjectStringthe subject line
bodyStringthe body of the email
optionsObjecta JavaScript object that specifies advanced parameters, as listed below

Advanced parameters

NameTypeDescription
attachmentsBlobSource[]an array of files to send with the email
bccStringa comma-separated list of email addresses to BCC
ccStringa comma-separated list of email addresses to CC
fromStringthe address that the email should be sent from, which must be one of the values returned by getAliases()
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
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" />
nameStringthe name of the sender of the email (default: the user's name)
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
replyToStringan email address to use as the default reply-to address (default: the user's email address)

Return

GmailApp — the Gmail service, useful for chaining

See also


starMessage(message)

Adds a star to this message and forces the message to refresh.

 
// Stars the first message in the first thread in your inbox
 var firstThread = GmailApp.getInboxThreads(0,1)[0];
 var message = firstThread.getMessages()[0];
 GmailApp.starMessage(message);
 

Parameters

NameTypeDescription
messageGmailMessagethe message to star

Return

GmailApp — the Gmail service, useful for chaining

See also


starMessages(messages)

Adds stars to these messages and forces the messages to refresh.

 
// Stars the first three messages in the first thread in your inbox
 var firstThread = GmailApp.getInboxThreads(0,1)[0];
 var coupleOfMessages = firstThread.getMessages().slice(0, 3);
 GmailApp.starMessages(coupleOfMessages);
 

Parameters

NameTypeDescription
messagesGmailMessage[]an array of messages to star

Return

GmailApp — the Gmail service, useful for chaining

See also


unstarMessage(message)

Removes a star from this message and forces the message to refresh.

 
// unstars the first message in the first thread in your inbox
 var firstThread = GmailApp.getInboxThreads(0,1)[0];
 var message = firstThread.getMessages()[0];
 GmailApp.unstarMessage(message);
 

Parameters

NameTypeDescription
messageGmailMessagethe message to unstar

Return

GmailApp — the Gmail service, useful for chaining

See also


unstarMessages(messages)

Removes stars from these messages and forces the messages to refresh.

 
// unstars the first three messages in the first thread in your inbox
 var firstThread = GmailApp.getInboxThreads(0,1)[0];
 var coupleOfMessages = firstThread.getMessages().slice(0, 3);
 GmailApp.unstarMessages(coupleOfMessages);
 

Parameters

NameTypeDescription
messagesGmailMessage[]an array of messages to unstar

Return

GmailApp — the Gmail service, 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.