Google Apps Script

Class GmailMessage

A message in a user's Gmail account.

Methods

MethodReturn typeBrief description
forward(recipient)GmailMessageForwards this message to new recipients.
forward(recipient, options)GmailMessageForwards this message to new recipients, with optional arguments.
getAttachments()GmailAttachment[]Gets all the attachments for this message.
getBcc()StringGets the comma-separated recipients bcc'd on this message.
getBody()StringGets the HTML content of the body of this message.
getCc()StringGets the comma-separated recipients cc'd on this message.
getDate()DateGets the date and time of this message.
getFrom()StringGets the sender of this message.
getId()StringGets the id of this message.
getPlainBody()StringGets the content of the body of this message without HTML formatting.
getRawContent()StringGets the raw content of this message.
getReplyTo()StringGets the reply-to address of this message (usually the sender).
getSubject()StringGets the subject of this message.
getThread()GmailThreadGets the thread that contains this message.
getTo()StringGets the comma-separated recipient(s) of this message.
isDraft()BooleanGets whether this message is a draft.
isInChats()BooleanGets whether this message is a chat.
isInInbox()BooleanGets whether this message is in the inbox.
isInTrash()BooleanGets whether this message is in the trash.
isStarred()BooleanGets whether this message is starred.
isUnread()BooleanGets whether this message is unread.
markRead()GmailMessageMarks the message as read.
markUnread()GmailMessageMarks the message as unread.
moveToTrash()GmailMessageMoves the message to the trash.
refresh()GmailMessageReloads this message and associated state from Gmail (useful in case the labels, read state, etc., have changed).
reply(body)GmailMessageReplies to the sender of this message using the reply-to address.
reply(body, options)GmailMessageReplies to the sender of this message using the reply-to address, with optional arguments.
replyAll(body)GmailMessageReplies to the sender using the reply-to address and all recipients of this message.
replyAll(body, options)GmailMessageReplies to the sender of this message using the reply-to address and all recipients, with optional arguments.
star()GmailMessageStars the message.
unstar()GmailMessageUnstars the message.

Detailed documentation

forward(recipient)

Forwards this message to new recipients. See the 'Email Body Size' entry on the Quota Limits tab of the Dashboard for the maximum allowable size of the email body.

 
// forward first message of first inbox thread to recipient1 & recipient2, both @example.com
 var firstThread = GmailApp.getInboxThreads(0,1)[0];
 var message = firstThread.getMessages()[0];
 message.forward("recipient1@example.com,recipient2@example.com");
 

Parameters

NameTypeDescription
recipientStringa comma-separated list of email addresses

Return

GmailMessage — this message, useful for chaining

See also


forward(recipient, options)

Forwards this message to new recipients, with optional arguments. The email can contain both plain text, and also an HTML body. See the 'Email Body Size' entry on the Quota Limits tab of the Dashboard for the maximum allowable size of the email body.

 
var firstThread = GmailApp.getInboxThreads(0,1)[0];
 var message = firstThread.getMessages()[0];
 message.forward("recipient1@example.com,recipient2@example.com", {
   cc: "myboss@example.com",
   bcc: "mybosses-boss@example.com,vp@example.com"
 });
 

Parameters

NameTypeDescription
recipientStringa comma-separated list of email addresses
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 GmailApp.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)
subjectStringa new subject line for the email

Return

GmailMessage — this message, useful for chaining

See also


getAttachments()

Gets all the attachments for this message.

Return

GmailAttachment[] — an array of Blob attachments for this message


getBcc()

Gets the comma-separated recipients bcc'd on this message.

This will be empty for all received messages, by definition.

 
var thread = GmailApp.getInboxThreads(0,1)[0]; // get first thread in inbox
 var message = thread.getMessages()[0]; // get first message
 Logger.log(message.getBcc()); // log bcc'd addresses
 

Return

String — the comma-separated recipients bcc'd on this message

See also


getBody()

Gets the HTML content of the body of this message.

 
var thread = GmailApp.getInboxThreads(0,1)[0]; // get first thread in inbox
 var message = thread.getMessages()[0]; // get first message
 Logger.log(message.getBody()); // log contents of the body
 

Return

String — the body content of this message

See also


getCc()

Gets the comma-separated recipients cc'd on this message.

 
var thread = GmailApp.getInboxThreads(0,1)[0]; // get first thread in inbox
 var message = thread.getMessages()[0]; // get first message
 Logger.log(message.getCc()); // log cc'd addresses
 

Return

String — the comma-separated recipients cc'd on this message

See also


getDate()

Gets the date and time of this message.

 
var thread = GmailApp.getInboxThreads(0,1)[0]; // get first thread in inbox
 var message = thread.getMessages()[0]; // get first message
 Logger.log(message.getDate()); // log date and time of the message
 

Return

Date — the date and time of this message


getFrom()

Gets the sender of this message.

 
var thread = GmailApp.getInboxThreads(0,1)[0]; // get first thread in inbox
 var message = thread.getMessages()[0]; // get first message
 Logger.log(message.getFrom()); // log from address of the message
 

Return

String — the email address of the message sender

See also


getId()

Gets the id of this message.

 
var thread = GmailApp.getInboxThreads(0,1)[0]; // get first thread in inbox
 var message = thread.getMessages()[0]; // get first message
 var id = message.getId();
 var messageById = GmailApp.getMessageById(id);
 Logger.log(message.getSubject() == messageById.getMessage()); // always logs true
 

Return

String — the message id


getPlainBody()

Gets the content of the body of this message without HTML formatting.

 
var thread = GmailApp.getInboxThreads(0,1)[0]; // get first thread in inbox
 var message = thread.getMessages()[0]; // get first message
 Logger.log(message.getPlainBody()); // log contents of the body
 

Return

String — the plain body content of this message

See also


getRawContent()

Gets the raw content of this message. This is equivalent to "Show Original" in the Gmail UI.

Return

String — the raw content of this message.


getReplyTo()

Gets the reply-to address of this message (usually the sender).

 
var thread = GmailApp.getInboxThreads(0,1)[0]; // get first thread in inbox
 var message = thread.getMessages()[0]; // get first message
 Logger.log(message.getReplyTo()); // logs reply-to address
 

Return

String — the email address for replies

See also


getSubject()

Gets the subject of this message.

 
var thread = GmailApp.getInboxThreads(0,1)[0]; // get first thread in inbox
 var message = thread.getMessages()[0]; // get first message
 Logger.log(message.getSubject()); // log subject line
 

Return

String — the subject of this message

See also


getThread()

Gets the thread that contains this message.

 
var thread = GmailApp.getInboxThreads(0,1)[0]; // get first thread in inbox
 var message = thread.getMessages()[0]; // get first message
 Logger.log(message.getThread().getFirstMessageSubject() ==
            thread.getFirstMessageSubject()); // always logs true
 

Return

GmailThread — the GmailThread that contains this message


getTo()

Gets the comma-separated recipient(s) of this message.

 
var thread = GmailApp.getInboxThreads(0,1)[0]; // get first thread in inbox
 var message = thread.getMessages()[0]; // get first message
 Logger.log(message.getTo()); // log the recipient of message
 

Return

String — the comma-separated recipient(s) of this message

See also


isDraft()

Gets whether this message is a draft.

 
var thread = GmailApp.getInboxThreads(0,1)[0]; // get first thread in inbox
 var message = thread.getMessages()[0]; // get first message
 Logger.log("is draft? " + message.isDraft());
 

Return

Boolean — whether this message is a draft


isInChats()

Gets whether this message is a chat.

 
var thread = GmailApp.getInboxThreads(0,1)[0]; // get first thread in inbox
 var message = thread.getMessages()[0]; // get first message
 Logger.log("is a chat? " + message.isInChats());
 

Return

Boolean — whether this message is a chat


isInInbox()

Gets whether this message is in the inbox.

 
var thread = GmailApp.getInboxThreads(0,1)[0]; // get first thread in inbox
 var message = thread.getMessages()[0]; // get first message
 Logger.log("is in inbox? " + message.isInInbox());
 

Return

Boolean — whether this message is in the inbox


isInTrash()

Gets whether this message is in the trash.

 
var thread = GmailApp.getInboxThreads(0,1)[0]; // get first thread in inbox
 var message = thread.getMessages()[0]; // get first message
 Logger.log("is in the trash? " + message.isInTrash());
 

Return

Boolean — whether this message is in the trash


isStarred()

Gets whether this message is starred.

 
var thread = GmailApp.getInboxThreads(0,1)[0]; // get first thread in inbox
 var message = thread.getMessages()[0]; // get first message
 Logger.log("is starred? " + message.isStarred());
 

Return

Boolean — whether this message is starred


isUnread()

Gets whether this message is unread.

 
var thread = GmailApp.getInboxThreads(0,1)[0]; // get first thread in inbox
 var message = thread.getMessages()[0]; // get first message
 Logger.log("is unread? " + message.isUnread());
 

Return

Boolean — the unread status of this message


markRead()

Marks the message as read.

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

Return

GmailMessage — this GmailMessage, useful for chaining

See also


markUnread()

Marks the message as unread.

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

Return

GmailMessage — this GmailMessage, useful for chaining

See also


moveToTrash()

Moves the message to the trash.

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

Return

GmailMessage — this GmailMessage, useful for chaining

See also


refresh()

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

 
var thread = GmailApp.getInboxThreads(0,1)[0]; // get first thread in inbox
 var message = thread.getMessages()[0]; // get first message
 // .. do bunch of stuff here
 message.refresh(); // make sure it's up to date
 // do more stuff to message
 

Return

GmailMessage — this message for chaining


reply(body)

Replies to the sender of this message using the reply-to address. See the 'Email Body Size' entry on the Quota Limits tab of the Dashboard for the maximum allowable size of the email body.

 
// respond to author of message with acknowlegment
 var firstThread = GmailApp.getInboxThreads(0,1)[0];
 var message = firstThread.getMessages()[0];
 message.reply("Got your message");
 

Parameters

NameTypeDescription
bodyStringthe body of the email

Return

GmailMessage — this message, useful for chaining

See also


reply(body, options)

Replies to the sender of this message using the reply-to address, with optional arguments. The email can contain both plain text, and also an HTML body. See the 'Email Body Size' entry on the Quota Limits tab of the Dashboard for the maximum allowable size of the email body.

 
// respond with HTML body text
 var firstThread = GmailApp.getInboxThreads(0,1)[0];
 var message = firstThread.getMessages[0];
 messageThread.reply("incapable of HTML", {
   htmlBody: "<b>some HTML body text</b>",
   noReply: true
 });
 

Parameters

NameTypeDescription
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 GmailApp.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)
subjectStringa new subject line for the email

Return

GmailMessage — this message, useful for chaining

See also


replyAll(body)

Replies to the sender using the reply-to address and all recipients of this message. See the 'Email Body Size' entry on the Quota Limits tab of the Dashboard for the maximum allowable size of the email body.

 
// respond to all recipients (except bcc'd) of last email in thread with acknowledgment
 var firstThread = GmailApp.getInboxThreads(0,1)[0];
 var message = firstThread.getMessages()[0];
 message.replyAll("Got your message");
 

Parameters

NameTypeDescription
bodyStringthe body of the email

Return

GmailMessage — this message,useful for chaining

See also


replyAll(body, options)

Replies to the sender of this message using the reply-to address and all recipients, with optional arguments. The email can contain both plain text, and also an HTML body. See the 'Email Body Size' entry on the Quota Limits tab of the Dashboard for the maximum allowable size of the email body.

 
// respond with HTML body text
 var firstThread = GmailApp.getInboxThreads(0,1)[0];
 var message = firstThread.getMessages[0];
 messageThread.replyAll("incapable of HTML", {
   htmlBody: "<b>some HTML body text</b>",
   noReply: true
 });
 

Parameters

NameTypeDescription
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 GmailApp.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)
subjectStringa new subject line for the email

Return

GmailMessage — this message, useful for chaining

See also


star()

Stars the message.

 
var thread = GmailApp.getInboxThreads(0,1)[0]; // get first thread in inbox
 var message = thread.getMessages()[0]; // get first message
 message.star(); // star the message
 

Return

GmailMessage — this GmailMessage, useful for chaining

See also


unstar()

Unstars the message.

 
var thread = GmailApp.getInboxThreads(0,1)[0]; // get first thread in inbox
 var message = thread.getMessages()[0]; // get first message
 message.unstar(); // unstar the message
 

Return

GmailMessage — this GmailMessage, 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.