Gmail in Agent Builder

The Gmail step lets an agent send, reply to, read and file mail in a Gmail mailbox as part of a run. It can email a customer when a job is finished, collect overnight messages into one summary, or reply in the thread when a supplier invoice arrives. Each step does one thing, picked from 9 actions, and hands what Gmail sends back to the next step. To start a run when mail arrives, use the Email received trigger with Provider set to Gmail. That trigger has its own guide: see Start an agent when an email arrives.

app.centrus.ai/app/agents/workflow-builder

Agents

Build modular AI workflows with reusable nodes

Job completed email

1,240 / 10,000 creditsValidateResetRunsSettingsUpdate & Publish

Job finished

Job status changed

Fetch the job

Get job

Write the visit note

GPT-5.6 Terra

Email the customer

1 action enabled

2

AI builderMap

1. 1Gmail in the Integration group of the Nodes panel.
2. 2The step on the canvas. Once Send email is chosen, the summary reads 1 action enabled.
3. 3Connection: the Gmail address this agent sends from.
4. 4To, filled from the job the earlier step fetched.
5. 5Subject, also filled from that job.

Centrus works alongside Gmail. The mailbox stays in Google, and the agent reads and sends through it. Connecting Gmail in chat does not connect an agent, and connecting an agent does not connect chat. For asking about mail in a conversation, see Gmail in chat. How connections differ across the product is covered in Integrations overview.

Open the agent in Agent Builder and find Gmail in the Integration group of the Nodes panel. It sits directly under Outlook. Drag it onto the canvas and connect the step before it to its left-hand side. Until you choose an action, its summary on the canvas reads No actions selected.

Job finished

Job status changed

Gmail

No actions selected

2

1. 1Gmail in the Integration group. Drag it onto the canvas.
2. 2The new step. It reads No actions selected until you choose an action in its Details panel.

On a phone, Agent Builder shows the canvas only. The Nodes panel is hidden on screens narrower than 768 pixels and the Details panel on screens narrower than 1,024 pixels, so you can follow an agent's steps on a phone but need a tablet or computer to add a Gmail step or change its settings.

09:41

Centrus

Agents

Build modular AI workflows with reusable nodes

Chase overdue invoices

Save and Publish

Job finished

Job status changed

Fetch the job

Get job

Write the visit note

GPT-5.6 Terra

Email the customer

1 action enabled

The Gmail connection belongs to this agent alone. It is separate from the Gmail card on the Integrations page, so connecting one does not connect the other. One connection covers every Gmail step in the agent, and the Email received trigger when its provider is Gmail, so you sign in once per agent. You can then add further Gmail addresses and choose, on each step, which one it uses.

You do not paste a password or an API key. Connect leaves the builder and opens Google in the same window. Sign in as the mailbox the agent should use. To send from jobs@meridianfm.co.uk, choose that account on Google's screen, not your own, unless you want mail to come from you. A shared inbox is available only when you can sign in as that mailbox. Google asks you to allow full Gmail access, described there as reading, composing, sending and permanently deleting all your email, and to see the email address on the Google account. The nine actions do less than that sentence: they read, send, reply, draft and file. They do not permanently delete mail.

1. 1Save the agent with Save draft. Until it has been saved once, the Connection section reads Save this workflow as a draft first, then connect the account. and Connect is greyed out.
2. 2Select the Gmail step. In the Details panel, open Connection and click Connect.
3. 3On Google, choose the account, then Allow.
4. 4You return to the builder. A notice reads Gmail connected for this agent, and Connection reads Connected, followed by the Gmail address.

There is no Copy from existing agent for Gmail. The sign-in is stored on this agent only. If Google does not complete the sign-in, Connection stays Not connected. If Centrus cannot open Google, you see Failed to start Gmail connection or Failed to connect Gmail.

Several mailboxes on one agent. Open Settings in the builder, then the Integrations section, and click Add another account. Each sign-in is listed with its address. You can rename one, or choose Set as primary. The primary address is the one a step uses when Account is left on Primary account (default). Account appears on a step only once the agent has two or more Gmail addresses, or when the address the step was pointing at has been disconnected. The list then shows Primary account (default) and each address, with (primary) on the primary one. A step that still points at a removed address shows This node's account is no longer connected to this agent.

Sharing and copying the agent. When you share an agent, its Gmail connection stays with it, and everyone who runs it uses that connection rather than their own, unless the agent is in per-user mode, described under Limits and good to know. When you duplicate an agent, the steps are copied but the Gmail sign-in is not, and each step's account choice is cleared, so connect Gmail again on the copy. For the details, see Share an agent.

Disconnecting. Disconnect on the step removes the primary Gmail address from this agent only. Any other addresses stay. If one remains, the oldest of them becomes the new primary. To remove a particular address, use the account row under Settings, then Integrations. Other agents keep their own connections, and the Gmail card in chat is not affected.

Select the step and open Actions in the Details panel. On a step in the agent's main flow the list is a set of radio buttons, so the step does one action. The line under the title reads What this step does with the connected Gmail account. There is no search box. The nine names, in order, are Send email, Reply to email, Read email, Get message, Get conversation, Create draft, Find emails, Download attachments and Move email to folder.

Send email is the action with the fields you will use most often. Recipients has To, CC and BCC. Separate several addresses with commas. Leave To blank only when the step is a tool for an Intelligence step, so the AI can choose the recipients. On the main flow an empty To has nobody to send to. CC is visible to everyone. BCC is hidden from the other recipients. Both are optional. Fixed message has Subject and Body. Leave them blank only when an AI is writing the email. The mail goes out from the Gmail address on Connection.

To use a value from an earlier step, open Step data references at the top of the Details panel and click a field to copy its reference, then paste it into To, Subject or Body. In the job agent, To holds the contact email from Fetch the job, and Subject holds the job reference. Text fields take a reference. Max results, Max messages, Within the last (hours), Max attachments and Max total size (bytes) are number fields, so a reference pasted into them is not kept.

Reply to email sends a reply in the same Gmail thread. Recipients come from the thread, so there is no To or CC. Reply body is required. An empty body does not send. Leave Message ID blank to reply to the incoming email, which is what you want after Email received. Tick Reply all to include the other recipients. The subject is kept, and Gmail is given a Re: prefix when the subject does not already have one.

What each action returns. Send email and Reply to email pass on the sent message. Create draft passes on the draft. Read email passes on one result holding up to 10 recent messages, each with its subject, sender, preview and id. On the main flow it has no query box, so it cannot be pointed at a sender or a date. Find emails is the action that searches: it passes on one item per matching message, including the body text and a list of attachments. Get message fetches one message in full and marks it as read. It has no Message ID box on the main flow, so use it as a tool, described below, or use Find emails when the flow itself needs the text. Get conversation loads the thread onto the same item, under the conversation, and does not emit one item per message and does not mark mail as read. Download attachments passes on one item per file. Move email to folder files the message under a label and passes the message on so a later step can file it again.

Find emails shows Find emails filter. Subject contains, Body contains and From contains match any part of that text, and capitals do not matter. From contains checks the address, not the sender's name. Allowed sender emails is an exact list, separated by commas. Within the last (hours) limits how far back to look. Leave it blank for no time limit. The hours are turned into a UTC date, so the search can include mail from the start of that UTC day, not only the last few hours. Folder is the Gmail label, and blank means INBOX. Max results defaults to 25 and will not go past 100. Only emails with attachments limits the list to messages that have a file. Find emails does not mark messages as read.

Download attachments shows Download attachments filter. Tick the file types you want, or leave them all unticked to download every attachment. Inline images, such as a logo in a signature, are left out. A file larger than 20 MB is skipped. The step takes the message id from the incoming item, which Find emails and Email received both provide. Move email to folder shows Destination folder, which for Gmail is a label name. Create the folder if it doesn't exist is ticked by default, so a missing label is created. The message is removed from the inbox. Leave Message ID blank to file the incoming email.

Create draft prepares a message in Gmail and does not send it. On the main flow it does not show To, Subject or Body. Those boxes appear only for Send email. Use Create draft as a tool, so the Intelligence step supplies the recipient, subject and body, or use Send email when you want to type them on the step. A draft does not keep CC or BCC.

A list such as Find emails passes on one item per message, so four invoices become four items. An Intelligence step reads those items together. Send email after that list sends one email, using the fields on the step, not one email per message. To reply to each message, or to file each one, put that step inside a Loop, described in Conditions, loops and approvals.

As a tool for an AI step. Connect a Gmail step to the Tools side of an Intelligence step and its Details panel changes. Actions becomes a search box where you can choose several, and the line reads Choose the tools this assistant can call. It fills the fields on the call. The AI decides when to call each one. Read email can then be given a search and a limit. Get message and Create draft can be given the id, the recipient and the text. The step's summary on the canvas shows how many actions are enabled, such as 2 actions enabled.

Supplier invoices

Gmail · Invoices

Write the reply

GPT-5.6 Terra

Read the thread

2 actions enabled

1

1. 1The Gmail step attached to the Intelligence step as a tool.
2. 2Actions: the Gmail actions the AI may call.
3. 3Pause for approval: each call the AI makes waits for someone to approve it in the Runs panel.

Pause for approval appears on every Gmail step but only applies to calls an AI makes, so it has no effect on a step in the main flow. To ask someone before a main-flow step sends or files mail, put an Approval step in front of it. Send email and Reply to email can also attach files already on the incoming item. Tick Attach files from incoming item binaries. The default limits are 20 files and 20 MB in total. You can raise them to 50 files and 25 MB.

Gmail does not have its own alert in the Trigger group. An agent starts from new mail with Email received, which watches one Gmail label and passes each matching message to the next step. Set Provider to Gmail and Label to the label name, such as Invoices, or INBOX for the inbox. The trigger uses the agent's Gmail connection, so if a Gmail step is already connected, the trigger can use that mailbox too. Setting up the label, the filters, what each run receives and how to test a message is covered in Start an agent when an email arrives. This section only shows where that trigger sits beside a Gmail step.

The trigger does not run while the inbox is quiet, and an email that misses the filters does not start a run. Nothing is watched until the agent is published. Because an email has nobody behind it, Integration mode cannot be Per-user on an agent that starts this way. Keep it on Agent-level, so the run uses the mailbox you connected on the agent. Filters, the label rules, and the error you see if the label is missing, are all in the email trigger guide rather than repeated here.

Each matching email becomes one run. The next step can reply with Reply to email, leaving Message ID blank, or file the message with Move email to folder. The trigger already includes the sender, subject, text and a list of attachments, so you do not need Read email or Get message simply to see what arrived.

Job finished

Job status changed

Fetch the job

Get job

Write the visit note

GPT-5.6 Terra

Email the customer

1 action enabled

AI builderMap

Job completed email writes to the customer when a visit is finished. Job finished is a BigChange webhook with Job status changed ticked, and the completed statuses chosen in BigChange. Fetch the job loads the job, including the contact and the site. Write the visit note turns that into a short plain note, and Email the customer uses Send email from jobs@meridianfm.co.uk, with To set to the contact email and Subject set from the job reference. The BigChange steps are described in BigChange REST in Agent Builder. Each finished job costs five credits or a little more.

Every day at 07:00

Daily at 07:00

Overnight mail

1 action enabled

Write the summary

GPT-5.6 Terra

Email the service desk

1 action enabled

AI builderMap

Morning inbox summary emails the service desk at 07:00 each day. The schedule is covered in Run an agent on a schedule. Overnight mail uses Find emails with Within the last (hours) set to 24 and Folder left as the inbox, and passes on one item per message. Write the summary reads them together and groups anything that needs a person, such as a supplier invoice or a message with no clear site. Email the service desk sends one email to the desk. The search costs 1 credit however many messages it returns.

Supplier invoices

Gmail · Invoices

Write the reply

GPT-5.6 Terra

Read the thread

2 actions enabled

Reply to the supplier

1 action enabled

AI builderMap

Supplier invoice reply answers invoices that land on the Invoices label. Supplier invoices is Email received with Provider set to Gmail, Label set to Invoices, From contains set to the supplier's domain and Subject contains set to invoice. Read the thread is a tool with Get conversation and Create draft, and Pause for approval is on, so a draft waits in the Runs panel before anyone relies on it. Write the reply checks the thread for the purchase order and the site. Reply to the supplier uses Reply to email with Message ID left blank, so the answer stays in the same thread. Each matching invoice starts its own run.

A dry run is the safe way to try a Gmail step that sends or files mail. Open Runs in the toolbar, click Run now and choose Dry run (no actions performed). Find emails, Read email and Get conversation call Gmail for real, so you see real messages. Send email, Reply to email, Create draft and Move email to folder are skipped, and nothing is sent or filed. Run for real performs every action, including the writes. Get message is treated as a read, so a dry run still fetches the message and still marks it as read. Use Find emails when you want to look without changing the mailbox.

{
  "messageId": "18f2c1a4b9e0d7",
  "subject": "Invoice 4418",
  "fromAddress": "accounts@harboursupplies.co.uk",
  "fromName": "Harbour Supplies",
  "receivedDateTime": "2026-10-09T05:40:00.000Z",
  "hasAttachments": true
}

Open a step in the run to see its output. The panel shows the first 50 items of each output, and later steps still receive all of them. A dry run costs 1 credit for the whole run. A real scheduled run of the morning summary costs more, because the Intelligence step is measured. For Run now, dry runs and the Runs panel in full, see Test an agent before it goes live.

A Gmail step costs 1 automation credit each time it runs successfully, whatever the action and however many messages or files it returns. A step that fails costs nothing. When the step is a tool, each call the AI makes costs 1 credit. Email received and a schedule are free, but every run they start costs 1 credit, like any other run.

Inside a Loop, the step is charged on every pass, so a Loop that replies to 40 messages costs 40 credits for that step. One Find emails is usually cheaper than fetching messages one at a time. For allowances, the per-run budget and how to see what each run cost, see Automation credits and usage limits.

• Per-user mode covers four actions. In Settings, Integration mode can be Per-user only when the agent starts from chat or from Run now. Send email, Read email, Get message and Create draft then use the Gmail account of the person who started the run, connected on their own Integrations page, not the agent's connection. Reply to email, Get conversation, Find emails, Download attachments and Move email to folder fail in that mode. The message says only sending and creating drafts are supported, which leaves out Read email and Get message. A schedule or Email received has nobody to borrow an account from, so those agents stay on Agent-level.
• Read email lists 10. On the main flow it returns the 10 most recent messages and has no box for a sender, a label or a date. Use Find emails to search. As a tool, the AI can pass a search and a limit.
• Find emails stops at 100. The default is 25. Get conversation returns 50 messages unless you set Max messages, and it will not return more than 100. Older messages in the thread are left out.
• Get message marks mail as read. There is no switch for that, and a dry run does it too. The action also has no Message ID field on the main flow. Call it from an Intelligence step, which can pass the id, or use Find emails, which includes the body and does not mark mail as read.
• Create draft has no fields on the main flow. To, Subject and Body are shown for Send email only. Attach Create draft as a tool so the AI fills them in. CC and BCC are not stored on the draft.
• About 8 MB per read. A single read that returns more than about 8 MB fails. Narrow Find emails, or lower Max results.
• Files. Download attachments skips inline images and any file over 20 MB. Sending files that are already on the item allows 20 files and 20 MB unless you raise the limits, up to 50 files and 25 MB.
• Labels, not folders. Folder on Find emails and Destination folder on Move email to folder are Gmail labels. A name such as Invoices must match a label. A slash nests one, such as Receipts/Processed. Move email to folder removes the inbox label. It does not remove every other label on the message.
• Published agents only. Email received only starts runs once the agent is published. Run now works on drafts.

• Gmail not connected to this agent. Open the step's Connection section and click Connect. If you have duplicated the agent, the copy needs its own sign-in. If you are in per-user mode, the person who started the run needs Gmail connected on their own Integrations page. The message then says the step needs their own Gmail, under Settings, then Integrations.
• Gmail account is no longer connected to this agent. The address this step was using has been disconnected. Choose another under Account, or connect it again. The same warning appears in the Account list before you run.
• Failed to start Gmail connection. Centrus could not open Google. Save the agent, then try Connect again. If Google sends you back without connecting, Connection stays Not connected.
• Reply to email needs a message ID. The step is not following an email, and Message ID is empty. Put it after Email received or Find emails, or paste the id.
• Reply to email needs a body. Reply body is empty. Type the reply, or paste a reference to the Intelligence step that wrote it.
• Reply to email could not resolve a recipient from the original message. The message has no sender address the reply can use. Open the message in Gmail and check the From line.
• Gmail label was not found. The label in Folder or Destination folder does not match a label in that mailbox. Check the spelling. Capitals do not matter. For Move email to folder, leave Create the folder if it doesn't exist ticked if the label is new.
• No action selected. The summary still reads No actions selected. Choose one under Actions.
• An email never starts the agent. The agent must be published, Provider must be Gmail, and the label must exist. Filters and the other checks are in Start an agent when an email arrives.
• The action is not supported in per-user mode. Reply to email, Get conversation, Find emails, Download attachments and Move email to folder need the agent's own connection. Switch Integration mode to Agent-level, or use Send email, Read email, Get message or Create draft.
• A field will not take a reference. It is a number field, such as Max results. Type a number, or leave it blank for the default.
• Find emails stops at 100 messages. That is the limit for one step. Narrow the filters, or run it more often so each run has less to collect.

The Gmail step offers 9 actions: 5 read from the mailbox and 4 change it. Every call is on the Gmail API at https://gmail.googleapis.com, for the signed-in mailbox (users/me). Where an action is listed with the same endpoint as another, it calls that endpoint with different filters.