V2NodesGmail Listener
Gmail Listener
V2

Gmail Listener

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.1.1.0 - Current release.
0.1.0.0 - Published after the completed V2 overhaul.
0.0.0.11 - Aligned the V2 connector contract and public help article.
0.0.0.7 - Initial release.

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.
  • 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 Gmail label name or label ID to monitor for unread messages.
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 String 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 Attachment rows emitted for the message.

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.
  • The listener runs on any supported cluster.