Start an agent when an email arrives

Email received starts a run for each new email that arrives in one Outlook folder or one Gmail label and passes the filters you set on it. The run receives the email (its sender, subject, text and a list of its attachments), and the steps after the trigger decide what to do with it: read the attachment, create a bill in Xero, create a job in BigChange or reply to the sender.

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

Agents

Build modular AI workflows with reusable nodes

Supplier invoices

1,240 / 10,000 creditsValidateResetDraft savedRunsSettings

Save and Publish6

Supplier invoices

Outlook · Inbox/Invoices

2

Download the invoice

1 action enabled

Read the invoice

1 file type · 4 fields

Create the bill

Create Bill

AI builderMap

Ready to publish

1. 1Email received in the Trigger group of the Nodes panel. Click it, or drag it onto the canvas.
2. 2The trigger on the canvas. Its summary shows the provider and the folder it watches, here Outlook and Inbox/Invoices.
3. 3Connection: the mailbox the agent uses. Once a mailbox is connected this section starts folded, so click it to see which account it is.
4. 4Mailbox: the Provider and the Folder (Outlook) or Label (Gmail) to watch.
5. 5How do we decide this is the right email?: the filters an email must pass before a run starts. Click the title to open it.
6. 6Save and Publish. Nothing is watched until the agent is published.

The trigger uses no credits while it waits, and none for emails that miss its filters. If you are still choosing between this and the other triggers, see Choose how an agent starts.

The trigger watches an Outlook or a Gmail mailbox through the agent's own connection. Whoever clicks Connect signs in to Microsoft or Google, and the mailbox they sign in to is the one the agent watches. The agent's other Outlook steps (or Gmail steps) use the same connection, so a reply sent by the agent comes from that mailbox too.

• Sign in as the mailbox you want watched. To watch accounts@harbourfm.co.uk, sign in to that account when you connect, not to your own.
• Shared mailboxes cannot be chosen. Centrus watches the mailbox of the account that signed in, and there is no option to pick a Microsoft 365 shared mailbox from it. If invoices go to a shared mailbox, ask your Microsoft 365 admin to forward them to a mailbox that can sign in for itself, and connect that one.
• One mailbox per trigger. To watch accounts@ and jobs@, build two agents.
• More than one account. If the agent has two or more Outlook accounts connected (you add them with Add another account in the agent's Settings), an Account list appears under Connection. Pick the one whose folder the trigger should watch.

Supplier invoices

Outlook · Inbox/Invoices

Download the invoice

1 action enabled

1. 1The mailbox the trigger watches.
2. 2Account, shown only when the agent has two or more accounts for the same provider.

Because an email has nobody behind it, the trigger cannot use Per-user integration mode, where steps use the credentials of whoever starts the run. Once Email received is the trigger, Integration mode in Settings is greyed out, and an agent still set to Per-user cannot be published:

This usually happens when a Chat Trigger agent set to Per-user is changed to start from email. Switch Integration mode to Agent-level before you swap the trigger. If you have already swapped, delete Email received, add a Chat Trigger for a moment, set Agent-level in Settings, then delete the Chat Trigger and add Email received again with its settings. Only the agent's owner or an organisation admin sees Integration mode.

1. 1In the Nodes panel, open Trigger and click Email received. An agent has one trigger, so remove any other first.
2. 2Select the trigger, click Mailbox in the Details panel to open it, and choose Outlook or Gmail under Provider.
3. 3Enter the Folder or Label to watch. It starts as inbox, and the next section explains what you can enter.
4. 4Save the agent. The mailbox can only be connected once the agent has been saved.
5. 5In the Connection section, which appears once a provider is chosen, click Connect. Sign in to the mailbox you want watched and allow access when Microsoft or Google asks, and you are brought back to the builder.
6. 6Check that Connection reads Connected with the right address, then open the filters, described below.

The Connection message changes as you go:

Once the agent is saved, the message still says Connect Outlook after saving this workflow. The saving is already done at that point, so click Connect. If your Microsoft or Google admin limits which apps can read mail, they may need to approve Centrus before the sign-in completes.

The trigger watches one folder or label and nothing else. An email in a subfolder of it does not count, and the folder or label must already exist, because Centrus does not create it.

For Outlook:

• inbox watches the inbox. Other top-level folders work by name, such as Archive or a folder called Invoices that sits beside the inbox.
• For a folder inside another one, give the path from the top: Inbox/Invoices, not Invoices. A name on its own is only looked for among top-level folders.
• Capitals do not matter, so inbox/invoices finds Inbox/Invoices.

For Gmail, enter the label's name, such as Jobs, or INBOX for the inbox. Capitals do not matter here either.

If an Outlook rule or a Gmail filter files emails into the folder for you, send a test email that the rule should catch and check that a run starts before you rely on it.

Centrus finds the folder when you publish, and stops with one of these messages if it cannot:

• Outlook folder "Invoices" was not found. Use Inbox, a folder name, or a path such as Inbox/Subfolder. Check the spelling, or give the full path if the folder sits inside the inbox.
• Multiple Outlook folders named "Invoices" exist at this level. Use a folder ID instead. Rename one of the folders in Outlook so the name is unique, then publish again.
• Gmail label "Jobs" was not found. Create the label in Gmail, or check its spelling.
• Email received needs a folder (Outlook) or label (Gmail) to subscribe to. The Folder or Label box is empty.
• We could not subscribe to this mailbox. Check the account is connected and that your Microsoft or Google admin allows mailbox notifications, then publish again. Check Connection reads Connected. If it does, ask your admin whether mailbox notifications are blocked.

Open How do we decide this is the right email? to set the filters. An email must pass every filter you fill in, and a filter left blank lets everything through. Capitals never matter. An email that fails is skipped before a run starts: it costs nothing and does not appear in Runs.

Supplier invoices

Outlook · Inbox/Invoices

Download the invoice

1 action enabled

1. 1Allowed sender emails (optional): full addresses, separated by commas. The sender must be one of them exactly, so invoices@northgatehousing.co.uk does not match an email from accounts@northgatehousing.co.uk.
2. 2From contains: any part of the sender's address, such as @northgatehousing.co.uk for everyone at Northgate Housing. Only the address is checked, not the sender's name, so Northgate Housing in this box matches nothing.
3. 3Subject contains: text that must appear somewhere in the subject. invoice matches Invoice INV-20931 and also Invoices overdue.
4. 4Body contains: text that must appear somewhere in the email's text.
5. 5Has attachments: Any, the default, lets every email through. Yes skips emails with no attachment, and No skips emails that have one.
6. 6Include inline images in attachment metadata: off by default. Pictures inside the email, such as a logo in a signature, are left out of the attachment list unless you tick it.

Some things the filters do not do:

• Each box is one phrase. Subject contains set to invoice, receipt looks for that exact text, comma included. It does not mean invoice or receipt. To accept either, leave the box wider, or blank, and decide in a later step.
• Has attachments does not look at the file. A PDF invoice, a Word letter and a spreadsheet all count the same, and in Gmail so does a picture in the email, such as a signature logo. Use the File Parser to check what the file actually is.
• Gmail treats every picture as inline. In a Gmail mailbox, a photo sent as an attachment is left out of the attachment list like a signature logo. If the agent needs photos from Gmail, such as pictures of a leak, tick Include inline images in attachment metadata.
• Text the filters cannot see. To decide on meaning, such as whether an email really is a job request, add an Intelligence step after the trigger. That step uses credits for every email that reaches it, so keep the filters as tight as you can in front of it.

Here is how the filters from the figure above treat three emails:

Each run starts with one email, and the trigger passes these details to the steps after it:

• subject, bodyText (the email's text with the formatting removed, up to 100,000 characters) and bodyPreview (its opening words).
• fromAddress and fromName, from (the two together), and the to and cc addresses.
• hasAttachments and attachments: each attachment's name, type and size, and whether it is inline. The files themselves are not fetched, as the next section explains.
• receivedDateTime and folder, and the email's ids (messageId, internetMessageId and conversationId), which steps such as Reply to email and Get conversation use to find it again.

To use a detail in a later step, type it as a reference, such as {{ trigger.json.subject }} or {{ trigger.json.fromAddress }}. The Step data references box in later steps does not list the email's details, so type them as shown here. To see real values, run the agent once and open the trigger step in Runs:

{
  "subject": "Invoice INV-20931 for September",
  "fromAddress": "invoices@northgatehousing.co.uk",
  "fromName": "Northgate Housing",
  "to": ["accounts@harbourfm.co.uk"],
  "bodyPreview": "Please find attached our invoice for…",
  "bodyText": "Please find attached our invoice for September…",
  "hasAttachments": true,
  "attachments": [{ "name": "INV-20931.pdf",
    "contentType": "application/pdf", "isInline": false }],
  "folder": "Inbox/Invoices",
  "receivedDateTime": "2026-10-09T08:12:04Z"
}

The trigger does not mark the email as read or move it. If you want the email filed once it has been dealt with, add an Outlook or Gmail step with Move email to folder at the end of the agent.

To read what is in an attachment, such as the order number on a PDF purchase order, add two steps after the trigger:

1. 1An Outlook step (or Gmail) with Download attachments turned on. It fetches every attachment from the email that started the run and passes each file on separately, ready for the File Parser.
2. 2A File Parser step. Tick the types of file to read, describe what to pull out under What to extract, and add a Structured field for each detail later steps need, such as po_number, site, required_by and total.

Purchase orders

Outlook · Inbox/Orders

Download the order

1 action enabled

1

Read the order

1 file type · 4 fields

Log the order

Append rows · Orders

1. 1Download attachments on an Outlook step fetches the files.
2. 2File types to parse. Files of a type you leave unticked are not read.
3. 3What to extract: say in plain words what to pull out of the file.
4. 4Structured fields (optional): one field for each detail, so later steps can use them by name.

Each file goes through the rest of the agent on its own. A supplier who attaches an invoice and a terms and conditions PDF sends two files down the line, and a step such as Create Bill would run for each. Tick only the type you expect and, in the File Parser, turn on Stop the branch when the file is missing or not a selected type so a logo or a spreadsheet does not carry on. The File Parser uses credits for every file it reads.

Every step you can add after the trigger, with its settings, is in Steps an agent can use.

Supplier invoices into Xero or Sage. Northgate Housing and other suppliers send invoices to accounts@harbourfm.co.uk, where an Outlook rule files them into Inbox/Invoices. The agent reads each PDF and creates a draft bill for the accounts team to check.

Supplier invoices

Outlook · Inbox/Invoices

1

Download the invoice

1 action enabled

2

Read the invoice

1 file type · 4 fields

3

Create the bill

Create Bill

4

File the email

1 action enabled

5

1. 1Email received on Inbox/Invoices, with Has attachments set to Yes so emails with no invoice are skipped.
2. 2Outlook with Download attachments.
3. 3File Parser with PDF ticked and fields for the supplier, invoice number, invoice date and total.
4. 4Xero with Create Bill, filled from the File Parser's fields. For Sage, use Sage with Create bill.
5. 5Outlook with Move email to folder, which files the email into Inbox/Invoices/Done so the team can see it has been handled.

Job requests into BigChange, with a reply. Customers such as Sarah Price at Riverside House email jobs@harbourfm.co.uk to report faults. The agent creates the job in BigChange and replies with the reference, and your team schedules the job in BigChange as normal.

Job requests

Outlook · Inbox/Jobs

1

Read the thread

1 action enabled

2

Work out the job

GPT-5.6 Terra

3

Create the job

Create job

4

Reply to the customer

1 action enabled

5

1. 1Email received on Inbox/Jobs.
2. 2Outlook with Get conversation, so the agent sees the whole thread and can tell a follow-up from a new request.
3. 3Intelligence, which reads the request and writes the job details: site, contact, fault and priority.
4. 4BigChange with Create job.
5. 5Outlook with Reply to email, which answers in the same thread with the job reference.

Purchase orders into a spreadsheet. Northgate Housing sends PDF purchase orders for work at Harbour View Apartments. The agent in the previous section downloads each PDF, reads the order number, site, required-by date and total, and appends a row to an Excel sheet with Append rows. To use Google Sheets instead, use Append row on a Google Sheets step.

• From the moment you publish. Centrus starts watching the folder when the agent is published. Emails already in the folder are never picked up, and nor are emails that arrive while the agent is a draft. Send any you still need into the folder again once the agent is live.
• Shortly after the email lands. Microsoft or Google tells Centrus when a new email arrives, and the run starts soon after. Centrus also checks each watched folder once an hour, so an email it was not told about still starts a run, later than usual.
• Once per email. Centrus remembers every email it has dealt with, including those that missed the filters, so the same email never starts two runs. A forwarded copy or a resent email is a new email, though, and starts a run of its own.

Each agent works through its emails one at a time. When 20 invoices arrive together, the first starts straight away and each of the others waits until the run before it has finished. Centrus looks for waiting emails about once a minute, so allow roughly a minute per email when a batch comes in. Nothing is lost while emails wait.

• An approval holds up the emails behind it. A run waiting for someone to approve still counts as running, so no other email for that agent starts until it is approved or rejected. A run can wait for up to 8 hours in all. If emails arrive steadily, make sure someone answers approvals promptly, or leave the Approval step out. More in Conditions, loops and approvals.
• When the organisation hits a limit. If the monthly allowance is used up, or 10 agent runs are already going across the organisation, the run cannot start. It is listed as failed in Runs with the reason, and that email is not tried again, so deal with it by hand or send it in again once the limit has cleared.

Every email starts its own run, replies included. When Sarah Price replies to an email about a job, her reply lands in the folder as a new email, goes through the filters like any other and starts a new run. That run knows nothing about the earlier one unless a step reads the thread.

• Reply in the same thread. Use Reply to email on an Outlook or Gmail step. It answers the email that started the run, so the customer sees one conversation rather than a new email.
• The agent's own replies do not start runs. They are saved in Sent Items, not in the folder the trigger watches.
• Read the thread before acting. Get conversation fetches the earlier emails in the thread (50 by default, up to 100), so an Intelligence step can see that a job already exists. Follow it with a Condition so Create job only runs for new requests.
• Replies pass the same filters. A reply's subject starts with Re:, so a Subject contains word that was in the original still matches. With Has attachments set to Yes, replies without a file are skipped.

Waiting costs nothing, and so does every email that misses the filters. An email that passes starts a run, which costs 1 automation credit plus its steps: 1 credit each time an Outlook, Gmail, Xero, Sage or BigChange step runs, and a measured amount of at least 2 for each Intelligence or File Parser step. The supplier invoice agent above uses about 6 credits per invoice.

On a busy mailbox, the filters set the bill. An agent that puts every email in a shared inbox through Intelligence pays for every newsletter, delivery notice and out-of-office reply that arrives:

Put the cheapest check that does the job on the trigger: a folder that a rule fills, the supplier's domain in From contains, or a word in Subject contains. Then let Intelligence decide only among the emails that get through. When an Intelligence step follows a trigger with no filters, Validation warns that Intelligence runs on every email in the folder.

To cap what one run may spend, set Per-run credit budget in Settings. How credits and limits work across Centrus: Automation credits and usage limits.

You do not need to wait for a real email. Open Runs, click Run now and choose Run for real or Dry run (no actions performed). The run uses the latest email in the watched folder, checked against your filters, and it works on a draft, so you can test before you publish.

• This folder has no mail yet. Send a test email into it, or use Simulate inbound mail. Send a test email into the folder and try again. There is no Simulate inbound mail option in the builder.
• A filter miss names the filter, such as Email received from-contains "@northgatehousing.co.uk" did not match sarah.price@riversidehouse.co.uk. or Email received sender allow-list does not include sarah.price@riversidehouse.co.uk. Send an email that should match, or check the filter.

Only the latest email can be tested. To test a particular one, send it into the folder again so it becomes the latest. Run now also runs on an email the live agent has already dealt with, so on a published invoice agent a full run creates a second bill. Use Dry run on an agent that is already live. More on testing: Test an agent before it goes live.

Changes to the trigger only take effect when you publish again. Until then the live agent keeps watching the folder, with the filters it was published with. To change the folder or the filters, edit them and click Update & Publish.

Before you replace Email received with another trigger, delete it or point it at a different mailbox, switch the agent to Draft first. Switching to Draft is what stops Centrus watching the mailbox. Publishing a different trigger over a live Email received does not, so the old mailbox can carry on starting runs.

1. 1Open Settings in the toolbar and change Status to Draft.
2. 2Click Revert to draft to confirm.
3. 3Make the change: swap the trigger, delete it or connect the other mailbox.
4. 4Publish again.

More on drafts and versions: Publish, pause and restore versions.

Disconnect under Connection removes the agent's Outlook (or Gmail) connection straight away, without asking you to confirm, and shows Outlook disconnected from this agent. Every Outlook step in the agent loses the connection, not only the trigger.

The agent stays published but no longer starts runs from new emails, and nothing in Runs shows that it has stopped. If you mean to stop the agent, switch it to Draft first and disconnect afterwards. To move to a different mailbox, follow the steps in the previous section. Emails that arrive while the agent is disconnected may not be picked up later, so check for any that need handling by hand.

Connecting and disconnecting accounts in more detail: Microsoft Outlook in Agent Builder and Gmail in Agent Builder.