Object reference

Gmail message

A GmailMessage is one email inside a Gmail thread. Call getFrom(), getSubject(), getDate(), getPlainBody(), or getAttachments() to inspect that single message.

GmailApp.GmailMessage

Start here

Get this object first

Search for a thread with GmailApp.search, then take the first message from it.

Code.gs

function showFirstSearchedMessageSubject() {
  const threads = GmailApp.search('newer_than:7d', 0, 1);
  if (!threads.length) return;
  const message = threads[0].getMessages()[0];
  Logger.log(message.getSubject());
}

Then use it

Common actions

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

Read the sender, subject, and date

This reads three details from the first message of a recent search and leaves the message unchanged.

GmailApp.GmailMessage

Show example code

Code.gs

function logFirstSearchedMessageDetails() {
  const threads = GmailApp.search('newer_than:7d', 0, 1);
  if (!threads.length) return;
  const message = threads[0].getMessages()[0];
  Logger.log('From: ' + message.getFrom());
  Logger.log('Subject: ' + message.getSubject());
  Logger.log('Date: ' + message.getDate());
}

Get the plain text body

This records only the length of the plain text body, so no email content is copied into the execution log.

GmailApp.GmailMessage

Show example code

Code.gs

function logFirstSearchedMessageBodyLength() {
  const threads = GmailApp.search('newer_than:7d', 0, 1);
  if (!threads.length) return;
  const message = threads[0].getMessages()[0];
  const plainBody = message.getPlainBody();
  Logger.log('Plain text body length: ' + plainBody.length);
}

List the attachment names

This lists the file names attached to the message and does not download or save the attachments.

GmailApp.GmailMessage

Show example code

Code.gs

function logFirstSearchedMessageAttachmentNames() {
  const threads = GmailApp.search('has:attachment newer_than:7d', 0, 1);
  if (!threads.length) return;
  const message = threads[0].getMessages()[0];
  const names = message.getAttachments().map((attachment) => attachment.getName());
  Logger.log(names.join(', ') || 'No attachments');
}

Technical reference

Exact names and signatures

Generated runtime and signature facts stay separate from the beginner actions above. Open method details only when you need them.

At a glance

Service: GmailApp
Reference symbol: GmailApp.GmailMessage
Object: GmailMessage
Runtime: From signature data

Open the Google reference source

Methods and signatures

Browse 32 methods

createDraftReply

From signature data Google source

createDraftReply(body: string): GmailApp.GmailDraft
createDraftReply(body: string, options: unknown): GmailApp.GmailDraft

createDraftReplyAll

From signature data Google source

createDraftReplyAll(body: string): GmailApp.GmailDraft
createDraftReplyAll(body: string, options: unknown): GmailApp.GmailDraft

forward

From signature data Google source

forward(recipient: string): GmailApp.GmailMessage
forward(recipient: string, options: GmailApp.GmailAdvancedParameters): GmailApp.GmailMessage

getAttachments

From signature data Google source

getAttachments(): GmailApp.GmailAttachment[]
getAttachments(options: GmailApp.GmailAttachmentOptions): GmailApp.GmailAttachment[]

getBcc

From signature data Google source

getBcc(): string

getBody

From signature data Google source

getBody(): string

getCc

From signature data Google source

getCc(): string

getDate

From signature data Google source

getDate(): Date

getFrom

From signature data Google source

getFrom(): string

getHeader

From signature data Google source

getHeader(name: string): string

getId

From signature data Google source

getId(): string

getPlainBody

From signature data Google source

getPlainBody(): string

getRawContent

From signature data Google source

getRawContent(): string

getReplyTo

From signature data Google source

getReplyTo(): string

getSubject

From signature data Google source

getSubject(): string

getThread

From signature data Google source

getThread(): GmailApp.GmailThread

getTo

From signature data Google source

getTo(): string

isDraft

From signature data Google source

isDraft(): boolean

isInChats

From signature data Google source

isInChats(): boolean

isInInbox

From signature data Google source

isInInbox(): boolean

isInPriorityInbox

From signature data Google source

isInPriorityInbox(): boolean

isInTrash

From signature data Google source

isInTrash(): boolean

isStarred

From signature data Google source

isStarred(): boolean

isUnread

From signature data Google source

isUnread(): boolean

markRead

From signature data Google source

markRead(): GmailApp.GmailMessage

markUnread

From signature data Google source

markUnread(): GmailApp.GmailMessage

moveToTrash

From signature data Google source

moveToTrash(): GmailApp.GmailMessage

refresh

From signature data Google source

refresh(): GmailApp.GmailMessage

reply

From signature data Google source

reply(body: string): GmailApp.GmailMessage
reply(body: string, options: GmailApp.GmailAdvancedParameters): GmailApp.GmailMessage

replyAll

From signature data Google source

replyAll(body: string): GmailApp.GmailMessage
replyAll(body: string, options: unknown): GmailApp.GmailMessage

star

From signature data Google source

star(): GmailApp.GmailMessage

unstar

From signature data Google source

unstar(): GmailApp.GmailMessage

Need the whole workflow?

Return to a task guide

Task guides cover setup, permissions, expected results, and troubleshooting as well as object methods.

Browse Gmail tasks