Gmail Module

Run a workflow for every email a Gmail mailbox receives, answer in the same thread, and continue the conversation when the sender replies.

The Gmail Module adds a Gmail Start event and Gmail behavior for the Output, Input and End Tasks on the Gmail Channel. When an email that matches the Environment's filter arrives, a Session starts at the Gmail Start event. A typical use: an organisation mails a CSV or Excel file, the Process reads it with the Read file Task, builds a report, and replies with it as an attachment of the Output Task. The same Process can be tested from the editor's chat before any email is sent.

How it works

The engine checks the connected mailbox every 15 seconds while it is active, and every minute after about five quiet minutes, so a new email usually starts the Process within 5 to 20 seconds. Each new email is recorded first, then handled:

• An email that matches the filter starts the Process. The email is available as {email}.
• An Output Task replies in the same Gmail thread.
• An Input Task waits for the answer. The reply continues the same Session, whatever its subject, because the engine recognises the email headers of its own messages.
• An End Task (optionally) sends a last message and closes the conversation. A later reply to a closed conversation starts a new one, or is ignored, as configured.

Emails are never lost or handled twice: an engine restart or a Gmail outage only delays them. Only emails that arrive after you connect the mailbox start the Process.

Configuration

The Gmail Module is configured per Environment, so Development and Production can read different mailboxes. Changes to the filters apply to the next new conversation without a redeploy.

Field	Type	Required	Description
Sign-in method	choice	Yes	Connect Gmail: sign in with Google, works for personal and Workspace accounts. Workspace delegation: a service account your Google Workspace admin authorised for the mailbox. Default: Connect Gmail.
Gmail account	button	With Connect Gmail	Connects, reconnects or disconnects the account. Owners and admins only. The sign-in is stored encrypted on the engine and never shown.
Service account JSON key	secret	With delegation	JSON key of a Google Cloud service account with domain-wide delegation for the scope https://www.googleapis.com/auth/gmail.modify.
Mailbox address	string	With delegation	The Workspace mailbox to read, e.g. reports@your-domain.com. Takes effect at the next deploy.
Only from these senders	list	No	One address (ops@acme.it) or domain (@acme.it) per line. Empty: any sender.
Subject contains	string	No	Only emails whose subject contains these words.
Only with this Gmail label	string	No	Only emails that carry this label, for example one set by a Gmail filter.
Only emails with attachments	boolean	No	Default: off.
Attachment types	string	No	Comma-separated extensions, e.g. csv, xlsx. At least one attachment must match.
Only unread emails	boolean	No	Skip emails someone already opened in Gmail. Default: off.
Advanced Gmail search	string	No	Extra Gmail search terms, e.g. -category:promotions.
Processed label	string	No	Label added to every handled email so people can see it in Gmail. Default: EW-Flow/Processed.
Mark as read after processing	boolean	No	Default: off.
Only authenticated senders	boolean	No	Ignore emails whose sender domain fails Google's DMARC/DKIM checks, so a forged sender can neither start nor continue a conversation. Default: on.
Reply to a finished conversation	choice	No	Start a new conversation (if it matches the filter) or Ignore it. Default: start a new one.

The filters apply to new conversations. Replies always reach their conversation, but only from people who were on the original email.

The {email} variable

Declared by the Gmail Start event (its Email variable field, {email} by default) and refreshed by every InputTask:

Path	Example	Description
{email.from}	ops@acme.it	Sender address.
{email.fromName}	Acme Ops	Sender display name.
{email.subject}	Monthly report	Subject.
{email.text}		Plain-text body (from the HTML part when there is no text part).
{email.reply}	APPROVE	The new text only, without the quoted history.
{email.html}		HTML body, when present.
{email.to}, {email.cc}		Recipients, comma-separated.
{email.receivedAt}	2026-09-30T10:00:00.0000000Z	When Gmail received it (UTC).
{email.isReply}	false	True when it continued a conversation.
{email.isTest}	false	True when the email was typed in the test chat.
{email.messageId}		Gmail id of the email.
{email.attachments}		All the attachments, as files: put it in an Output Task's Attachments to send them all on.
{email.attachments.count}	2	Number of attachments.
{email.attachments.0}		The first attachment as a file, for the Read file Task or an Output's Attachments. {email.attachments.0.name}, .type and .size (bytes) describe it.
{email.attachments.names}	sales.csv, notes.pdf	All names.

Attachments are saved when the email is handled: up to 10 MB each and 25 MB per email. A larger one is listed (name, type, size) without its content. Where files are kept is set by the Standard Module's File storage setting.

Tasks

Gmail Start

Starts the Session for a new email and writes the email variable ({email} by default), which the editor then knows as declared. The attachments are already saved as files: read one with the Standard Module's Read file Task ({email.attachments.0}) or send them on with an Output Task's Attachments.

Gmail Start is the Gmail Channel's own start: a Process may have other starts next to it (one per Channel, for example a Chat start), and an email always begins at Gmail Start, wherever it is in the diagram.

Testing from the chat. Start a chat on the Environment in the editor (or with the chat_start_session assistant tool): the Gmail Start event asks for the email, and your next chat message becomes {email}. Its first line is the subject, the rest is the body, and the files you attach with the paperclip are the attachments. With the assistant you can also pass the email as test data (startNodeId = the Gmail Start's id, testData = {"subject": "Monthly report", "text": "Please build it.", "from": "ada@acme.it"}): the flow then starts at once, without asking. {email.isTest} is true. The rest of the flow runs on the chat: Output messages and their attachments appear there (with a download link), and Input Tasks wait for your next chat message. Nothing is sent from the mailbox.

On any other Channel (a Slack or SMS session, a reminder) Gmail Start stops the Session with a "starts Gmail sessions only" error instead of running the flow without {email}. A plain Start event also works on the Gmail Channel (flows built before Gmail Start), but it declares nothing and cannot be tested from the chat; when a Process has both, the email begins at Gmail Start.

OutputTask (Channel: Gmail)

Replies in the conversation's thread. The Message supports variables, e.g. Hi {email.fromName}, your report is ready. Attachments lists the files to attach: file variables such as {report} (from Create file) or {email.attachments} (all the files of the email), separated by commas. At most 10 files and 15 MB per email. The reply is queued and sent within seconds, in order, exactly once.

InputTask (Channel: Gmail)

Sends the optional Message as a question, then waits for the reply. The reply text (without quoted history) is stored in Store result in, its attachments in Store files in (optional), and {email} is replaced with the reply. The Session waits until someone replies; there is no time limit.

EndTask (Channel: Gmail)

Closes the conversation. It sends nothing: a closing mail is an OutputTask right before the End Event.

Example: reply with a report

1. Gmail Start: Environment filter Only from @acme.it, Attachment types csv.
2. Read file (Standard Module): File {email.attachments.0}, Read as Text, Store in {csv}.
3. JavaScript Task: build the report from context.csv into context.reportHtml.
4. Create file (Standard Module): File name report.html, Content {reportHtml}, Store in {report}.
5. OutputTask: Message Hi {email.fromName}, here is your report., Attachments {report}.
6. EndTask.

Test it from the editor's chat first: type a subject on the first line, attach the CSV, and the report comes back as a download in the chat.

Notes

• Connect Gmail uses a Google permission that Google reviews for production apps. Until the platform's review is complete, the sign-in may need renewing every 7 days; the settings show needs reconnecting when it does.
• Mail sent by the mailbox itself and automatic replies (out-of-office) never start a conversation.
• Email records are kept 90 days; the emails themselves stay in Gmail.