Class GmailApp

Creates a draft email message. The size of the email (including headers) is quota limited.

// The code below creates a draft email with the current date and time.
const now = new Date();
GmailApp.createDraft(
    'mike@example.com',
    'current time',
    `The time is: ${now.toString()}`,
);

Parameters

Return

GmailDraft — the newly created GmailDraft

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

See also

• createDraft(recipient, subject, body, options)

Creates a draft 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) is quota limited.

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

Parameters

Advanced parameters

Return

GmailDraft — the newly created GmailDraft

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

See also

• createDraft(recipient, subject, body)

Create a new user label of the given name.

// Creates the label @FOO and logs label: FOO
Logger.log(`label: ${GmailApp.createLabel('FOO')}`);

Parameters

Return

GmailLabel — the newly created label

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

See also

• deleteLabel(label)

Deletes the specified label.

// Have to get the label by name first
const label = GmailApp.getUserLabelByName('FOO');
GmailApp.deleteLabel(label);

Parameters

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

See also

• createLabel(name)

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.
const me = Session.getActiveUser().getEmail();
const 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

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

See also

• sendEmail(recipient, subject, body, options)

Retrieve an email message draft by ID.

Use this in conjunction with getId() on Gmail drafts.

// Get the first draft message in your drafts folder
const draft = GmailApp.getDrafts()[0];
// Get its ID
const draftId = draft.getId();
// Now fetch the same draft using that ID.
const draftById = GmailApp.getDraft(draftId);
// Should always log true as they should be the same message
Logger.log(
    draft.getMessage().getSubject() === draftById.getMessage().getSubject(),
);

Parameters

Return

GmailDraft — the draft with the given ID

Throws

Error — if no draft with the given ID can be found

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

Retrieves all draft messages.

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

Return

GmailMessage[] — an array of draft Gmail messages

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

Gets all Gmail draft messages.

const drafts = GmailApp.getDrafts();
for (let i = 0; i < drafts.length; i++) {
  Logger.log(drafts[i].getId());
}

Return

GmailDraft[] — an array of Gmail draft messages

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

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
const threads = GmailApp.getInboxThreads();
for (let i = 0; i < threads.length; i++) {
  Logger.log(threads[i].getFirstMessageSubject());
}

Return

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

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

Retrieves a range of Inbox threads irrespective of labels.

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

Parameters

Return

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

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

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

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

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
const message = GmailApp.getInboxThreads(0, 1)[0].getMessages()[0];
// Get its ID
const messageId = message.getId();
// Now fetch the same message using that ID.
const messageById = GmailApp.getMessageById(messageId);
// Should always log true as they should be the same message
Logger.log(message.getSubject() === messageById.getSubject());

Parameters

Return

GmailMessage — the message with the given ID

Throws

Error — if no message with the given ID can be found

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

See also

• getThreadById(id)

Retrieve all messages in the specified thread.

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

Parameters

Return

GmailMessage[] — array of messages corresponding to this thread

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

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
const thread = GmailApp.getInboxThreads(0, 2);
const messages = GmailApp.getMessagesForThreads(thread);
for (let i = 0; i < messages.length; i++) {
  for (let j = 0; j < messages[i].length; j++) {
    Logger.log(`subject: ${messages[i][j].getSubject()}`);
  }
}

Parameters

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

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

See also

• getMessagesForThread(thread)

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

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

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

Return

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

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

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

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

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

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

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

Return

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

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

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

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

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

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

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

Return

GmailThread[] — an array of starred Gmail threads

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

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

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

Gets a thread by ID.

Use this in conjunction with getId() on Gmail threads.

// Gets the first inbox thread.
const firstThread = GmailApp.getInboxThreads(0, 1)[0];
// Gets the same thread by ID.
const threadById = GmailApp.getThreadById(firstThread.getId());
// Verifies that they are the same.
console.log(
    firstThread.getFirstMessageSubject() ===
        threadById.getFirstMessageSubject(),
);

Parameters

Return

GmailThread — The thread with the given ID or null if not found.

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

See also

• getMessageById(id)

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

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

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

Return

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

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

Retrieves a label given the label name.

const labelObject = GmailApp.getUserLabelByName('myLabel');

Parameters

Return

GmailLabel — the Gmail label with the given name

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

Retrieves a list of user-created labels.

// Logs all of the names of your labels
const labels = GmailApp.getUserLabels();
for (let i = 0; i < labels.length; i++) {
  Logger.log(`label: ${labels[i].getName()}`);
}

Return

GmailLabel[] — array of user created labels

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

Marks this message read and forces the message to refresh.

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

Parameters

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

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
const message = GmailApp.getInboxThreads(0, 1)[0].getMessages()[0];
GmailApp.markMessageUnread(message);

Parameters

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

See also

• markMessageRead(message)

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.
const threadMessages = GmailApp.getInboxThreads(0, 1)[0].getMessages();
const messages = [threadMessages[0], threadMessages[1], threadMessages[2]];
GmailApp.markMessagesRead(messages);

Parameters

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

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
const threadMessages = GmailApp.getInboxThreads(0, 1)[0].getMessages();
const messages = [threadMessages[0], threadMessages[1], threadMessages[2]];
GmailApp.markMessagesUnread(messages);

Parameters

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

See also

• markMessagesRead(messages)

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

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

Parameters

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

See also

• markThreadUnimportant(thread)

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

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

Parameters

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

See also

• markThreadUnread(thread)

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

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

Parameters

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

See also

• markThreadImportant(thread)

Marks this thread unread and forces the thread to refresh.

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

Parameters

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

See also

• markThreadRead(thread)

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

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

Parameters

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

See also

• markThreadsUnimportant(threads)

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

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

Parameters

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

See also

• markThreadsUnread(threads)

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

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

Parameters

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

See also

• markThreadsImportant(threads)

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

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

Parameters

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

See also

• markThreadsRead(threads)

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

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

Parameters

Return

GmailApp — the Gmail service (useful for chaining)

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

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
const firstThread = GmailApp.getInboxThreads(0, 1)[0];
const messages = firstThread.getMessages();
const toDelete = [messages[0], messages[1]];
GmailApp.moveMessagesToTrash(toDelete);

Parameters

Return

GmailApp — the Gmail service (useful for chaining)

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

See also

• moveMessageToTrash(message)

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

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

Parameters

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

See also

• moveThreadToInbox(thread)
• moveThreadToSpam(thread)
• moveThreadToTrash(thread)

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

// Find a thread not already in your inbox
const thread = GmailApp.search('-in:inbox')[0];  // Get the first one
GmailApp.moveThreadToInbox(thread);

Parameters

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

See also

• moveThreadToTrash(thread)
• moveThreadToSpam(thread)
• moveThreadToArchive(thread)

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

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

Parameters

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

See also

• moveThreadToTrash(thread)
• moveThreadToInbox(thread)
• moveThreadToArchive(thread)

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

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

Parameters

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

See also

• moveThreadToInbox(thread)
• moveThreadToSpam(thread)
• moveThreadToArchive(thread)

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

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

Parameters

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

See also

• moveThreadsToInbox(threads)
• moveThreadsToSpam(threads)
• moveThreadsToTrash(threads)

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

// Find two threads not already in your inbox
const firstTwoThreads = GmailApp.search('-in:inbox', 0, 2);
GmailApp.moveThreadsToInbox(firstTwoThreads);

Parameters

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

See also

• moveThreadsToTrash(threads)
• moveThreadsToSpam(threads)
• moveThreadsToArchive(threads)

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

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

Parameters

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

See also

• moveThreadsToInbox(threads)
• moveThreadsToTrash(threads)
• moveThreadsToArchive(threads)

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

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

Parameters

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

See also

• moveThreadsToInbox(threads)
• moveThreadsToSpam(threads)
• moveThreadsToArchive(threads)

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

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

Parameters

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

See also

• refreshMessages(messages)

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

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

Parameters

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

See also

• refreshMessage(message)

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

const firstThread = GmailApp.getInboxThreads(0, 1)[0];
// ...Do something that may take a while here....
GmailApp.refreshThread(firstThread);
// ... Do more stuff with the thread ...

Parameters

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

See also

• refreshThreads(threads)

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

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

Parameters

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

See also

• refreshThread(thread)

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
const threads = GmailApp.search('is:starred subject:"IMPORTANT"');

Parameters

Return

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

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

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.
const threads = GmailApp.search('is:starred subject:"IMPORTANT"', 10, 10);

Parameters

Return

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

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

Sends an email message. The size of the email (including headers) is quota limited.

// The code below will send an email with the current date and time.
const now = new Date();
GmailApp.sendEmail(
    'mike@example.com',
    'current time',
    `The time is: ${now.toString()}`,
);

Parameters

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

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) is quota limited.

// Send an email with a file from Google Drive attached as a PDF.
const 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

Advanced parameters

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

See also

• sendEmail(recipient, subject, body)

Sets the current message access token that enables the script to access the current GmailMessage properties.

Only Google Workspace Add-on projects using Gmail current message scopes require this method.

function handleAddonActionEvent(e) {
  GmailApp.setCurrentMessageAccessToken(e.messageMetadata.accessToken);
  const mailMessage = GmailApp.getMessageById(e.messageMetadata.messageId);
  // Do something with mailMessage
}

Parameters

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

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

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

Parameters

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

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
const firstThread = GmailApp.getInboxThreads(0, 1)[0];
const coupleOfMessages = firstThread.getMessages().slice(0, 3);
GmailApp.starMessages(coupleOfMessages);

Parameters

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

See also

• starMessage(message)

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

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

Parameters

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

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
const firstThread = GmailApp.getInboxThreads(0, 1)[0];
const coupleOfMessages = firstThread.getMessages().slice(0, 3);
GmailApp.unstarMessages(coupleOfMessages);

Parameters

Return

GmailApp — the Gmail service, useful for chaining

Authorization

Scripts that use this method require authorization with one or more of the following scopes or appropriate scopes from the related REST API:

• https://mail.google.com/

See also

• unstarMessage(message)