Appearance
0044: Receipts by email to a GetMy address per company
Context
ADR 0031 (2026-10-01) chose Xero's Files inbox as the way receipts arrive: the owner forwards an email, the attachment lands in Xero, GetMy Books links it. It rejected our own receiving address but kept it as the fallback "if the Files inbox falls short". docs/not-doing.md recorded "Receiving files ourselves (local folder, upload page, our own email address)".
On 2026-10-30 the Files inbox fell short. Rob Duncan forwarded a British Airways booking confirmation to WEALTH TECH PROFESSIONALS LIMITED's Xero inbox. The receipt was in the email body, with no PDF. Xero accepted the email and kept nothing, with no error; he noticed only because he checked. Most receipts people actually get (airlines, Apple, Octopus, Lothian Buses, Domino's, hotels) are body-only emails, so a flow that depends on an attachment loses a lot of evidence silently.
Decision
Accepted by the Product Owner on 2026-10-30:
- Each company gets a GetMy receiving address. A random local part at the receipts subdomain of getmy.group (
<token>@receipts.getmy.group), issued and rotated by the signed-in owner withreceipts_address, shown to the owner only, stored per company under row-level security. It is a capability like the Xero inbox address (ADR 0031 consequence): anyone who knows it can put a file into the company's Xero inbox, and only the owner's Approve links a file to a record. - Mail is received by a Cloudflare Email Worker and handed to the app over HTTPS. The Worker posts the raw message to
POST /receipts/inbound, outside Cloudflare Access like/stripe/webhook(ADR 0037 decision 4), signed with HMAC-SHA256 over a timestamp and the body usingRECEIPTS_INBOUND_SECRET. The app trusts nothing but that signature; the company comes from the receiving address, resolved inside a security definer function, never from a header. CLAUDE.md rule 4 is met by the address token standing in for the session: the owner issued it, and it maps to exactly one company. - The file is kept in Xero, not by us. An attachment that is a PDF or an image is uploaded to the company's Xero Files inbox (
POST /files.xro/1.0/Files). An email with no such attachment is rendered to a PDF from its text and structure (headings, paragraphs, tables, links as text), with tracking pixels and remote images dropped and nothing fetched from the internet, and that PDF is uploaded. Bytes are held in memory for the request only (ADR 0032 precedent); GetMy Books stores no file. ADR 0031 decision 2 ("never receives, holds or stores the file") is amended to: never stores the file. - Every email gets a result, and the sender is told. The outcome is
filed(what was uploaded),duplicate(seen before, by content hash or by message id),needs_review(nothing could be kept, or the address is right but the message is not a receipt we can read) orrejected(unknown address, too large, a type we do not keep). The outcome, the message id, the content hash, the sender, the subject, the Xero file ids and the parsed fields in integer pence are recorded inreceipt_emailunder row-level security, written by a security definer function (the webhook pattern of ADR 0037). The Worker replies to the sender with the result in one sentence. Nothing is written to the activity log: no person acted (ADR 0033). - Figures parsed by code are search terms and flags, never book entries. A pure parser reads the supplier, date, total, VAT shown, payment method and last four card digits from the email text into integer pence. They drive matching (
findCandidates,planReceiptReconciliation,matchCard), duplicate detection and VAT sense checks, and they are shown to the owner. Nothing from them is written to Xero: ADR 0022 point 2 stands, amended to say that code may read a receipt to search and flag. The file is the evidence; the owner's Approve attaches it. - Not-doing is reworded. The row "Receiving files ourselves" becomes: "A local folder or an upload page. Receipts arrive by email to the company's Xero inbox or its GetMy address (ADR 0044); GetMy Books stores no file." The row "Reading the owner's mailbox" stands.
Consequences
- New settings
RECEIPTS_INBOUND_SECRETandRECEIPTS_DOMAIN, optional as the Stripe group is; the route answers 503 until both are set. Deploy allowlist, compose file and Doppler prd gain them; the root-owned compose copy on the NAS is reinstalled (ADR 0023). - Owner actions: enable Cloudflare Email Routing on
receipts.getmy.group(MX records on the subdomain only, so getmy.group's own mail is untouched), deploy the Worker frominfra/cloudflare/receipts-worker/with its secret and the app URL, route the subdomain's catch-all to it, and add an Access Bypass application formcp.getmy.group/receipts/inboundas was done for/health. - A new dependency for MIME parsing and one for PDF writing, both pure JavaScript (the runtime image has no RUN step, ADR 0028); checked by
pnpm audit, semgrep and trivy like every other. - ADR 0026's inventory gains
receipt_email(metadata, hashes and parsed figures; never the body) andinbound_address. Retention followsledger_write(six years, QD-35 pending). - The Xero
filesscope is believed to cover upload; a spike confirms it before the first real email, and a 403 is reported as "reconnect". - Worst case: a stranger who learns the address drops files into the company's Xero inbox. They sit there until the owner links one after Approve, and the owner rotates the address. Senders are told, so a misdirected receipt is noticed.
- A new capability CAP-02.16 "Receipts by email" (capability model 1.13.0) governed by SPEC-021. SPEC-005's "Out of scope: receiving files ourselves" is amended with a dated banner.