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, a Send email Task 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, unless you set Process emails received since (below).

An email the filter matched but that was skipped (the sender's domain is not authenticated, the sender is not on the allowed senders list, a reply from someone who was not on the conversation) does not start anything. It appears on the workspace Logs page, with the Environment and the reason, as a GmailMessageSkipped warning (the assistant's list_logs shows it too). Emails that simply do not match the filter are not listed.

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.
Process emails received since	date	No	Emails already in the inbox received since this date (and matching the filter) start the Process too. Applied once, at the mailbox's next check after you connect it or change the date; emails already handled never start again. Never further back than the email records are kept (90 days). Empty: only new emails.
Send from (alias)	string	No	The address replies (Output Task) and Send email go out from: empty = the mailbox itself, or one of its verified Send mail as addresses (Gmail → Settings → Accounts), e.g. the Google Group the mailbox receives for. Checked at deploy: an address Gmail does not list as verified fails the deploy and names the ones that work.
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.

Send email

Sends a new email from the Environment's connected mailbox, on any Channel: a scheduled run, a form, a chat, or a Gmail conversation (to answer the email that started the conversation, in its thread, use the Output Task). It works with both sign-in methods.

Field	Description
To, Cc, Bcc	Addresses separated by commas or semicolons; variables allowed. At most 50 recipients.
From	Optional. Empty: the Environment's Send from (alias), else the mailbox. Otherwise the mailbox or one of its verified Send mail as addresses (checked at deploy and when the step runs).
Reply-to	Optional reply-to address.
Body	Template (an email template from Storage → Templates), HTML or Text, as in the other Send email Tasks. With a template, an empty Subject uses the template's own.
Attachments	Files, one per line or comma-separated: ref-session:{report}, ref-storage:invoice.pdf, {email.attachments.0}... Max 10 MB in total.
Store the message id in	The Gmail id of the sent email.

The email is sent at once (the step fails with the reason when Gmail refuses it) and appears in the mailbox's Sent folder. A step that runs again after an engine restart does not send it twice.

OutputTask (Channel: Gmail)

Replies in the conversation's thread, from the Send from (alias) when one is set. 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.

Reply from a group address

Invoices often arrive at a Google Group (e.g. billing@your-domain.com) whose member mailbox (e.g. invoices@your-domain.com) is the one connected. By default replies go out from the connected mailbox, an address the sender never wrote to. To reply from the group's address instead:

1. Sign in to Gmail as the connected mailbox (invoices@) and open Settings → See all settings → Accounts → Send mail as → Add another email address.
2. Enter the group address (billing@your-domain.com) and the name people should see (e.g. Acme S.r.l. – Billing). Keep Treat as an alias ticked.
3. Google sends a confirmation email to the group address. As a member, the connected mailbox receives it: click the link or enter the code. The address must show as confirmed in that list; one still waiting for confirmation is refused.
4. In the Environment's Gmail settings, set Send from (alias) to billing@your-domain.com and deploy. The deploy log confirms Replies and Send email go out from …, or lists the addresses the mailbox can send as when the alias is not usable yet.

From then on replies (OutputTask) and Send email without a From go out from the group address, with that name. Mail from the alias itself never starts a conversation, so a reply that lands back in the group cannot loop. If Google later removes the alias, deploy fails with the same list, and a reply sent meanwhile goes out from the mailbox, with a warning in the logs.

With Delegation (service account) instead of Connect Gmail, the same applies: the alias is added in the delegated user's Gmail settings, or by a Workspace admin.

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 (or from its Send from alias) and automatic replies (out-of-office) never start a conversation.
• Mailbox of a Google Group. When invoices arrive at a group (e.g. billing@) and a member's mailbox is connected, Google re-sends the mail, which breaks the sender's DMARC check at the member's mailbox: the module still accepts it when Google's own ARC chain confirms the original sender. To answer from the group's address, see Reply from a group address.
• Reading the Send mail as addresses needs no extra permission: Google allows it with the gmail.modify permission the module already asks for.
• Email records are kept 90 days; the emails themselves stay in Gmail.