gmail@3.1.0

getContentsFromMessages(options)

getMessageById(messageId, [options])

sendMessage(message)

This adaptor exports the following from common:

alterState

combine()

cursor()

dataPath()

dataValue()

each()

field()

fields()

fn()

fnIf()

lastReferenceValue()

log()

merge()

sourceValue()

Functions

getContentsFromMessages

getContentsFromMessages(options) ⇒ Operation

Downloads contents from messages of a Gmail account.

Param	Type	Description
options	Options	Customized options including desired contents and query.

This operation writes the following keys to state:

State Key	Description
data	The returned message objects, of the form { messageId, ...contents }
processedIds	An array of string ids processed by this request

Example: Get a message with a specific subject

getContentsFromMessages(
  {
    query: 'subject:my+test+message'
  }
)

Example: Get messages after a specific date, with subject and report.txt attachment

getContentsFromMessages(
  {
    query: 'after:15/01/2025',
    contents: [
      'subject',
      { type: 'file', name: 'metadata', file: 'report.txt'}
    ]
  }
)

Example: Get metadata without downloading requested attachments

getContentsFromMessages(
  {
    query: 'after:2026/07/01',
    contents: [
      'body',
      { type: 'file', name: 'report', file: /\.xlsx$/ }
    ],
    fetchAttachments: false
  }
)

---

getMessageById

getMessageById(messageId, [options]) ⇒ Operation

Downloads contents from a single message of a Gmail account, identified by its Gmail API message id.

Param	Type	Description
messageId	string	Gmail API message id to fetch.
[options]	MessageIdOptions	Customized options including desired contents.

This operation writes the following keys to state:

State Key	Description
data	The returned message object, of the form { messageId, ...contents }

Example: Download attachments for a specific message identified by an earlier step

getMessageById(
  $.data.messageId,
  {
    contents: [
      { type: 'file', name: 'report', file: /\.xlsx$/ }
    ]
  }
)

---

sendMessage

sendMessage(message) ⇒ Operation

Sends a Gmail message using the provided configuration. Supports attachments and standard email fields like subject, body, and recipients.

Param	Type	Description
message	SendMessageOptions | Array.<SendMessageOptions>	The message configuration object or array of objects.

This operation writes the following keys to state:

State Key	Description
data	The Gmail API response from sending the message.

Example

sendMessage({
  to: 'recipient@example.org',
  subject: 'Test Message',
  body: 'Hello from OpenFn!',
  attachments: [
    { filename: 'test.txt', content: 'Some text content' }
  ]
})

---

Interfaces

MessageContent

Used to isolate the type of content to retrieve from the message.

Properties

Name	Type	Description
[type]	string	Message content type. Valid types: from, date, subject, body, archive, file.
[name]	string	A custom description for the content type.
[archive]	RegExp | string	Identifier to isolate the desired attachment when type is 'archive'. Use a regular expression for pattern matching or a string for a literal match. Required if type is 'archive'.
[file]	RegExp | string	Identifier to isolate the desired attachment when type is 'file' or 'archive'. Use a regular expression for pattern matching or a string for a literal match. Required if type is 'file' or 'archive'.
[maxLength]	number	Maximum number of characters to retrieve from the content.

---

MessageIdOptions

Configurable options provided to getMessageById.

Properties

Name	Type	Default	Description
[contents]	Array.<(string|MessageContent)>	['from', 'date', 'subject']	An array of strings or MessageContent objects used to specify which parts of the message to retrieve.
[email]	string		The user account to retrieve messages from. Defaults to the authenticated user.
[fetchAttachments]	boolean	true	Whether to download file and archive attachments. When false, matched attachments are returned as filename-only objects without content.

---

Options

Configurable options provided to the Gmail adaptor.

Properties

Name	Type	Default	Description
[query]	string		Gmail search query string.
[contents]	Array.<(string|MessageContent)>	['from', 'date', 'subject']	An array of strings or MessageContent objects used to specify which parts of the message to retrieve.
[processedIds]	Array.<string>		Ignore message ids which have already been processed.
[email]	string		The user account to retrieve messages from. Defaults to the authenticated user.
[maxResults]	int		Maximum number of messages to process per request. Default is 1000.
[fetchAttachments]	boolean	true	Whether to download file and archive attachments. When false, matched attachments are returned as filename-only objects without content.

---

SendMessageOptions

Configurable fields for composing an outbound Gmail message.

Properties

Name	Type	Description
to	string	Recipient email address.
subject	string	Subject line of the email.
body	string	Email body content.
[attachments]	Array.<{filename: string, content: (string|Buffer)}>	Optional list of files to attach.

---