Appearance
0031: Receipts arrive through Xero's Files inbox
Context
On 2026-10-01 Rob asked Claude Desktop for all the receipts for one supplier, which Sam had asked for. Claude found every one in Rob's Gmail, but GetMy Books had no way to attach them in Xero (#120).
SPEC-005 planned two ways for a file to reach GetMy Books: a local allowed folder (stdio) and a web upload page. Neither fits what happened:
- Rob uses the claude.ai connector, so a local folder never reaches him.
- An upload page means downloading each receipt, then uploading it again.
The alternatives were considered and rejected:
| Option | Why not |
|---|---|
| The model passes the file to a tool | A chat connector gives Claude an attachment's readable content, not the file. Passing bytes means the model typing them out: a 150 KB PDF is about 200,000 characters, slow and costly, and one wrong character corrupts it. |
| GetMy Books reads Gmail or Outlook itself | A Google or Microsoft grant per user, kept alive by GetMy Books. Gmail's read scope is restricted: Google expires an unverified app's grant every 7 days, and verification needs a yearly paid assessment. Every owner, and every accountant for every client, would have to connect a mailbox. |
| Our own receiving address (Cloudflare Email Worker) | It works, but we would hold files Xero already holds for us. Kept as the fallback if the Files inbox falls short (sender control, Gmail auto-forward checks). |
Every Xero organisation already has its own email address. Attachments emailed to it land in the Files inbox, and the Xero Files API can link a file to a transaction (POST /files.xro/1.0/Files/{FileId}/Associations).
Decision
Accepted by the Product Owner on 2026-10-01 ("the email forwarding to the Xero inbox is the perfect solution, let's go for that"):
Receipts arrive by email to the organisation's Xero Files inbox.
- The owner forwards them, or sets a mail filter to forward them.
- A client can forward them on behalf of their accountant.
- Nobody connects a mailbox to GetMy Books, and nothing changes per email provider.
GetMy Books never receives, holds or stores the file. It lists the inbox and links a file to the Xero record it supports. The file stays in Xero.
The model handles only references: a file ID, its name, size and date. Figures the model reads from a receipt or email are search terms only (ADR 0022).
Linking is a Xero write. It is previewed, then confirmed by ID (M4). The confirm needs a human approval the model cannot give (AUDIT C5), and each link is logged in
ledger_write.Superseded:
- SPEC-005's local allowed folder and web upload page, and QD-20's decision on how files arrive;
- ADR 0022 point 3 and its upload-page consequence.
ADR 0022's rule stands: attach evidence, never capture receipts.
Consequences
- The Xero app needs the Files API scope (
files; confirm the name under Xero's granular scopes). Each entity reconnects once, together with the SPEC-006 and management-reporting scopes. - A spike comes first. One real FEAW receipt is forwarded, then listed and linked through the API. It checks two things:
- that FEAW's Xero plan includes the Files API;
- that a linked file shows as an attachment on the transaction (
HasAttachments).
- Nothing new for ADR 0026 (data protection): GetMy Books stores no file.
- The inbox address is a capability: anyone who knows it can drop files into the inbox. Those files only sit there until someone links them, and linking needs human approval. The owner treats the address like any inbox address.
docs/not-doing.mdgains two rows: our own upload page or folder, and reading the owner's mailbox.
Amended 2026-10-01
Decided by the Product Owner on 2026-10-01 (QD-28: "yes do that"; "yeah 'Not FEAW' inbox is good"):
- The inbox address is returned to the signed-in owner, on request.
receipts_inbox_addressgives a company's Xero Files inbox address only to a session with access to that company. Claude can then forward receipts with the owner's own mail connector (Microsoft 365 or Gmail), in the owner's chat, after the owner says yes, and only to that address. - GetMy Books still never reads the mailbox. It holds no mail grant and sees no email. The owner's connector is the owner's own, turned on in Claude by the owner. Points 1 to 3 of the decision stand.
- A receipt the company did not pay is set aside, never deleted. Withdrawn 2026-10-01, see below. After the owner presses Approve, it is moved to a Xero Files folder named "Not <entity>" (for FEAW, "Not FEAW"), made if missing. Moving is a Xero write: previewed, confirmed by ID, approved in the card (AUDIT C5), and logged in
ledger_write. A file linked to a record, or paid with one of the company's own cards, is not moved.
Consequences of the amendment:
- The address now passes through the model to the owner. It was already the owner's to know, and a file dropped into the inbox still needs the owner's approval to be linked, so the capability point above stands.
docs/not-doing.mdis unchanged: GetMy Books reads no mailbox and receives no file.
Amended 2026-10-01: set-aside withdrawn
Found with the Product Owner on 2026-10-01. Xero has renamed Files to Documents, with Inbox and Archive tabs; folders live under Archive. Its Smart Document Capture reads receipts, marks each Match or Review, and matches them to transactions itself.
GetMy Books moved three files through the Files API (PUT /Files/{id} with a FolderId) into a new folder "Not FEAW". The folder was made, but it showed empty in Documents, and the files still showed in the Documents Inbox. Xero's Documents does not reflect folder moves made through the Files API. The Files API inbox listing can also differ from what Documents shows: 47 files against 76 that day.
So point 3 of the amendment above is withdrawn. GetMy Books moves no file. The owner archives a receipt that is not the company's in Xero Documents (Documents, select it, Archive, then a folder). GetMy Books leaves matching in Documents to Xero, and keeps forwarding receipts to the inbox, attachments_missing, and bank reconciliation.
Amended 2026-10-30 by ADR 0044
The Files inbox fell short: a body-only receipt forwarded to it was accepted and kept nothing. ADR 0044 adds the recorded fallback: each company also gets a GetMy receiving address, handled by a Cloudflare Email Worker and the app. Decision 2 ("never receives, holds or stores the file") now reads: GetMy Books never stores the file. It receives a forwarded email, holds its bytes in memory for the request only, and puts the file in the company's Xero Files inbox. Every other decision here stands.