V2NodesGmail Listener
Gmail Listener
V2

Gmail Listener

Polls Gmail for unread messages and emits them into your Workflow by using Gmail labels.

Revision History

0.0.0.7 - Initial release.

Connection

Use this Connection to store the Google OAuth client registration and Gmail tokens used by the Gmail sender and listener Nodes.

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

Setup Notes

  1. In Google Cloud, enable the Gmail API and create an OAuth client for the Gmail account you want to monitor.
  2. Add the Flowgear OAuth redirect URI shown by the Connection designer to the OAuth client's allowed redirect URI list.
  3. In the Flowgear Console, create a Connection of type Gmail, enter Client Id and Client Secret, then click Connect your Account.
  4. Complete the Google sign-in and consent flow. The Connection requests offline access and consent prompts so Google can return a Refresh Token for long-lived runtime use.
  5. Leave Scopes at its default value unless you have a specific reason to change it. The default scope is https://www.googleapis.com/auth/gmail.modify.
  6. Set MonitoredFolder to a Gmail label name or label ID such as INBOX.
  7. Test the Connection after authorization to confirm Flowgear can authenticate against Gmail.

Methods

The Node exposes one listener method. It mirrors the Microsoft Email listener surface, but uses Gmail labels in place of mail folders.

Listen

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

Parameter Type Description
Connection Connection The Gmail OAuth Connection used to authenticate the request.
MonitoredFolder String The 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 email rows that include message metadata such as messageId, sender, recipients, subject, body, isBodyHtml, emailDate, providerCode, providerStatus, and attachments.

Response child properties

Property Type Description
messageId String The Gmail message ID for the emitted email.
sender String The sender email address.
recipients String A semicolon-delimited list of all recipients on the email.
subject String The email subject line.
body String The email body content.
isBodyHtml Boolean true when body contains HTML.
emailDate String The sent or received email date serialized as text.
providerCode String Provider-specific code, when Gmail returns one.
providerStatus String Provider-specific status text, when Gmail returns one.
attachments Array The attachment objects emitted for the email.

attachments child properties

Property Type Description
name String The attachment filename.
contentType String The attachment MIME type.
content Stream The attachment content stream. If Workflow state is persisted between steps, Flowgear can serialize this content as Base64 text.

Usage Notes

  • MonitoredFolder, ProcessedFolder, and ErrorFolder accept Gmail label names or label IDs, not Exchange-style folders.
  • When FireMethod is PerMessage, the listener emits one row for the email and includes all attachments on that row.
  • When FireMethod is PerAttachment, the listener emits one row per attachment and repeats the parent email metadata on each row.
  • If ProcessedFolder is blank, the listener marks successfully processed messages as read. If ProcessedFolder is set, the listener removes the monitored label and applies the processed label instead.
  • If ErrorFolder is set and message processing fails, the listener removes the monitored label and applies the error label without marking the message as read.
  • If ProcessedFolder or ErrorFolder references a missing custom label, the listener creates that label when it first needs it.
  • The listener runs for up to 30 seconds per invocation and polls approximately every 5 seconds while no unread messages are available.
  • Attachment content is emitted as a stream at runtime. If workflow state is persisted between steps, Flowgear can serialize that content as Base64 text.
  • Gmail Listener runs on any supported cluster.