Gmail Listener v2

Gmail is an email service used to receive, organize, and process mailbox content by using labels, threads, unread state, and message metadata.

The Flowgear Gmail Listener Node polls Gmail for unread messages under a selected label and emits message-shaped rows into a Workflow, which makes it useful when you need to react to inbound email, attachments, or mailbox-driven process triggers.

Revision History

0.0.0.7 - Initial release.
0.0.0.11 - Aligned the Runtime connector contract.
0.1.0.0 - Completed the Runtime overhaul.
0.1.1.0 - Maintenance release.
0.1.1.4 - Renamed the Response and Attachments output fields to PascalCase, for example MessageId, Sender, Attachments, Name, ContentType and Content.

Connection

This Connection stores the Gmail OAuth client registration and mailbox tokens used by the sender and listener Nodes.

Property Type Description
Client Id String OAuth client identifier issued for the Gmail app registration.
Client Secret Masked OAuth client secret issued for the Gmail app registration.
Access Token Masked OAuth access token used for Gmail API calls.
Refresh Token Masked OAuth refresh token used to renew the access token when needed.
Scopes String Space-delimited Gmail OAuth scopes requested during authorization. The default value is https://www.googleapis.com/auth/gmail.modify.

Setup Notes

  • Enable the Gmail API for the target Google Cloud project and create an OAuth client.
  • Add the Flowgear OAuth redirect URI shown by the Connection designer to the OAuth client's allowed redirect URI list.
  • Create a Gmail Connection in Flowgear, enter Client Id and Client Secret, then connect the mailbox account.
  • Set MonitoredFolder to a Gmail label name or label ID such as INBOX.
  • ProcessedFolder and ErrorFolder also use Gmail labels, not Exchange-style folders.
  • The authorization request asks Google for offline access, so a Refresh Token is stored and the Access Token is renewed automatically when it expires. If Google rejects the refresh token, reconnect the account.
  • The Node expects a usable Access Token or Refresh Token. If neither is present, runtime execution fails fast.
  • The default scope https://www.googleapis.com/auth/gmail.modify is sufficient for the supported sender and listener operations, including reading messages and applying labels.
  • Connection test performs a lightweight Gmail profile request.

Methods

The Node exposes one listener method for inbound mailbox polling.

Listen

Polls the configured Gmail label every five seconds for unread messages and emits one row per message or one row per attachment.

Parameter Type Description
Connection Connection Gmail OAuth Connection used to authenticate the listener request.
MonitoredFolder String Required. Gmail label name or label ID to monitor for unread messages, for example INBOX. The label must already exist.
ProcessedFolder String Optional Gmail label name or label ID to apply after successful processing.
ErrorFolder String Optional Gmail label name or label ID to apply after failed processing.
FireMethod Enum Controls whether the listener emits one row per message or one row per attachment. Use PerMessage or PerAttachment.
Return Type Description
Response Array Emitted Gmail message rows. Query-style listener rows do not include mutation-style default fields.

Response child properties

Property Type Description
MessageId String Gmail message ID for the emitted email.
Sender String Sender email address.
Recipients String Semicolon-delimited list of recipients collected from the email headers.
Subject String Email subject line.
Body String Decoded email body content.
IsBodyHtml Boolean true when Body contains HTML content.
EmailDate String Sent or received timestamp serialized in round-trip format.
Attachments Array Attachments for the message. Empty when the message has no attachments.

Attachments child properties

Property Type Description
Name String Attachment filename.
ContentType String Attachment MIME type.
Content Stream Attachment content stream. If Workflow state is persisted between steps, Flowgear can serialize this content as Base64 text.

Usage Notes

  • Listener rows stay message-shaped and do not include top-level default status fields.
  • Empty polls are non-error outcomes. When no unread messages are available, the listener waits for the next poll interval.
  • If the first provider call for the listener fails, that Gmail error surfaces to the Workflow instead of being converted into an empty success result.
  • When FireMethod is PerMessage, all attachments are grouped onto the same emitted row.
  • When FireMethod is PerAttachment, the listener repeats the parent message metadata on one row per attachment.
  • If ProcessedFolder is blank, successfully processed messages are marked as read. If it is set, the monitored label is removed and the processed label is applied instead.
  • If ErrorFolder is set and message processing fails after the message is found, the monitored label is removed and the error label is applied without marking the message as read.
  • Missing custom labels referenced by ProcessedFolder or ErrorFolder are created on demand. A missing MonitoredFolder label is not created and fails the listener.
  • If a message has no attachments, FireMethod PerAttachment emits one row with an empty Attachments array.
  • The listener runs on any supported cluster.
  • When upgrading to version 0.1.1.4, refresh the Node's templates and update Workflow references to the PascalCase output fields, for example MessageId instead of messageId.