Workspace agents · 10 min
Run a Workspace Agent When Email Arrives
Workspace agents can run automatically when email arrives. This walkthrough uses a Payroll Assistant that reads Homebase daily reports, totals hours by employee, and keeps the next payroll calendar event up to date.
Walkthrough
Step by step
Create a workspace agent
Open Agents, choose Create workspace agent, and name the agent Payroll Assistant.
Workspace agents
Automation agents
Run reports, read workspace data, and act on events.
Start from Agents, then create a workspace agent.
Use a narrow name and purpose. It makes logs, permissions, and troubleshooting much easier to understand later.
Write clear payroll instructions
Tell the agent which sender and subject pattern to look for, how your pay dates work, and where to maintain the curated totals.
Give the agent the sender, subject pattern, pay schedule, and the calendar output you expect.
Include real examples of sender, subject, pay dates, and period dates so the agent can infer the next pay period correctly.
Allow the agent to read mailbox messages
In Read access, enable Mailbox messages. This lets the agent inspect incoming email that has landed in the workspace mailbox.
Check Mailbox messages so the agent can read incoming mail and attachments.
If the workflow depends on attachments, the agent still needs Mailbox messages access because attachments are opened from the mailbox record.
Allow calendar writes
Enable Calendars read access and Calendar events write access. The agent uses these permissions to find or create the payroll event on the default calendar.
Read access
Write access
The payroll agent needs both calendar context and permission to update the payroll event.
For payroll tracking, a calendar event is a durable place for the current totals until you submit them to payroll software.
Turn on the Email received trigger
In Event triggers, check Email received. Save the agent so it runs automatically whenever a new workspace email arrives.
Check Email received before saving the agent.
Keep Run on schedule on only if you also want periodic backstop runs. The Email received trigger is what makes the agent react to new mail.
Run a backfill when you first set it up
After saving, run the agent once and ask it to search the last four weeks of mailbox messages. This lets it build the next payroll event from recent reports.
Maria Lopez: 38.5 hours Devon Lee: 34.0 hours Sam Patel: 41.25 hours Source: Daily Report emails from no-reply@joinhomebase.com
The agent should maintain one upcoming pay-date event instead of scattering duplicate notes.
After the backfill, future Homebase emails can incrementally update the same upcoming pay-date event.
Before you finish
Launch checklist
- The workspace already receives the Homebase emails in Mail.
- The agent instructions include sender, subject pattern, pay schedule, and desired output.
- Mailbox messages read access is enabled.
- Calendars read access and Calendar events write access are enabled.
- Email received is selected under Event triggers.
- A first manual run backfills the current pay period from recent messages.
Fix common issues
Troubleshooting
The agent does not run when email arrives.
Open the agent settings and confirm Email received is checked under Event triggers. Also confirm the new email actually appears on the Mail page.
The agent reports that it cannot read email.
Enable Mailbox messages under Read access, then rerun the agent.
The agent cannot maintain the payroll event.
Enable Calendars read access and Calendar events write access so it can find, create, and update the calendar event.
Keep learning