What the agent does
This is for a company that sells bookkeeping software to freelancers and one-person businesses: designers, translators, tutors, photographers. Most of their business expenses arrive by email, as a receipt from a software subscription, an invoice from a coworking space, an order confirmation for a lens, and at the end of each month the app asks them to upload receipts that are sitting in their inbox. Many never do until the accountant asks in spring. The software company saves one agent as a template that names Gmail at the read level, "connections": [{"name": "gmail", "access": "read"}], and makes one agent from it per user who turns the feature on.
The company connects a Gmail account of its own first, because a template names connections its creator has. When a user turns the feature on, the backend calls POST /o/{org}/agents {"template": "<template id>", "name": "receipts-<user id>"}, then POST /o/{org}/agents/{agent}/connections {"type": "app", "name": "gmail"}, and opens the authorize_url for that user, who signs in on Google's page. Because the template names the read level, Google asks that user for gmail.readonly alone, and every run's token is refreshed for that scope alone: the agent can read mail and cannot send, label or delete it.
On a run the agent calls users.messages.list with userId set to me and a q in Gmail's own search syntax for last month's mail that looks like a purchase: after: and before: dates, words such as receipt, invoice, order and payment, and has:attachment as one of the alternatives, following nextPageToken until the list ends. Google's reference says each listed message carries only an id and a threadId, so it reads each one with users.messages.get, and downloads a PDF or image attachment with users.messages.attachments.get. Messages from the user's own clients paying them are income, not expenses, and the prompt names those senders so the agent leaves them out.
For each receipt it records the seller, the date, the total, the currency, the tax amount when the receipt states one, and what was bought in a few words, quoted from the receipt. It saves each attachment, or the email itself as a PDF when the receipt is the email body, as an artifact of the run. Anything it cannot read a total from goes in a needs-a-look list with the subject and sender. It categorizes nothing for tax and creates no entry in the books: the user confirms each receipt in the app, which then attaches it to the transaction it matches.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "<agent id>",
"input": "Collect my business receipts from October 2026. Call users.messages.list with userId me and q 'after:2026/10/01 before:2026/11/01 (receipt OR invoice OR \"order confirmation\" OR \"payment received\" OR has:attachment) -from:me', following nextPageToken. Read each with users.messages.get. Skip messages from my clients, who pay me: billing@northwindmedia.example, accounts@harbor-press.example. Skip newsletters and marketing mail with no amount charged. For each receipt, download a PDF or image attachment with users.messages.attachments.get, or save the message as a PDF if the receipt is the email body, as receipts/<date>-<seller>.pdf. Return only JSON: {receipts: [{seller, date, total, currency, tax_shown, items (under 10 words, quoted), file, message_id}], needs_a_look: [{subject, from, date, why}]}. Do not send, label, archive or delete any mail."
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
The answer is JSON in the session's result and in the run.completed webhook, and the receipt files come back as the session's artifacts, each with a url the app downloads from. The app shows each receipt beside the bank or card transaction it most likely matches, and the user confirms, corrects or discards each one.
What the user checks: that a receipt is a business expense at all (a personal order from the same shop looks identical), the total and currency against the card statement, and the needs-a-look list, which holds the receipts whose total the agent could not read. How an expense is treated for tax is a question for the user and their accountant, and the app keeps it there.
Run it on every first day of the month
On the first of each month the app's scheduler sends one POST /o/{org}/sessions per user with the feature on, with their agent id as agent, last month's dates and their client senders in input, and a request_id that is a UUID v5 of the user id and the month. A retried job starts no second run, and every user's run starts at once; runs past the key's concurrent limit wait queued.
Before a tax deadline, a user can ask the app to collect a whole quarter or year, which starts the same request with a wider date range.
The use case this job follows, with its automation and trigger: Run an agent per customer task.
Why run it on Rush?
Each user signs in to Google on Google's page and that sign-in belongs to their own agent, at the read level the template names: one user's run can read only that user's mailbox, and the software company registers no Google app and holds no Gmail token. Each session lists the Google account it acted as in accounts, and GET /o/{org}/sessions?account=<email> lists every run that read a mailbox, which is the answer to a user who asks.
One template serves every user. When the app learns a new kind of receipt, such as marketplace payout statements, one PATCH to the template's instructions reaches every next run. Each run has its own computer and a record of each Gmail call and what its model calls cost, so the company can see what a month of receipts costs per user.
Frequently asked questions
Can the agent send or delete mail?
No. The template names Gmail at the read level, so each user's sign-in asks Google for gmail.readonly alone, and the prompt forbids sending, labeling and deleting as well. Rush's docs note a token can carry more when a person granted Rush more earlier, which is one more reason the prompt forbids it.
Does it read all of my email?
It reads the messages a Gmail search for last month's purchase words returns, the same search the user could type into Gmail, and opens those. The prompt keeps it to that list, and the transcript records every message it opened.
What about receipts that only live in an online account, not in email?
The agent finds only what reached the inbox. A seller that sends a "your invoice is ready" email with a link and no amount shows up in the needs-a-look list, so the user knows to download it from the seller's site.
Does the user need a Rush account?
No. They sign in to Google from the bookkeeping app. The agents, their runs and their cost belong to the person who created the software company's API key.
More Gmail jobs
More jobs like this: Run an agent per customer task
- Which Supplier Prices Went Up This Month? A Field-Service App's Check of Each HVAC Contractor's OneDrive Price Lists (OneDrive)
- How Did My Client's Site Do Last Month? A Reporting App Drafts Each Agency's Client Reports From Vercel Web Analytics (Vercel)
- What Were Our Numbers Last Month? An Investor-Update App's Read-Only Metrics From Each Startup's Neon Database (Neon)