Appearance
SPEC-021: Receipts by email
Business intent
A receipt forwarded to Xero's Files inbox is kept only if it is an attachment. On 2026-10-30 a British Airways booking confirmation, whose receipt was in the email body, was accepted by Xero and lost without an error. Most receipts are body-only emails. GetMy Books gives each company its own receiving address, keeps attachments, turns a body-only receipt into a PDF, puts the file in the company's Xero inbox, records a result for every email and tells the sender, so no receipt is lost silently and every one can be matched and attached through the existing card. Protects SM-3.
User story
When I forward a receipt, whether it is a PDF or just an email, I want it to become a file in my company's Xero inbox with a reply telling me it did (or why not), and I want Claude to see what arrived, what it matches and what still needs me.
Scope
- Address (ADR 0044 decision 1).
receipts_addressreturns the company's receiving address to a signed-in owner with access to it, issuing one when none exists;receipts_addresswithrotate: truereplaces it. The local part is 20 lower-case letters and digits fromrandomBytes; the domain isRECEIPTS_DOMAIN. Stored ininbound_addressunder row-level security. A company is issued its address when its Xero connection is saved (new or reconnected), so the owner takes no separate step (#407). Until the settings are set the tool is not an error: it says the GetMy address is not switched on for this service yet and names the one address to use meanwhile, the Xero Files inbox (fromreceipts_inbox), for receipts with a PDF or photo attached. - One address (#407). Every reply that shows an address recommends one.
receipts_inboxrecommends the company's GetMy address when the settings are set and the company has one, because it keeps a body-only receipt as a PDF and replies; the Xero Files inbox address is then kept in the JSON only, as not recommended. Otherwise it recommends the Xero Files inbox and says a body-only receipt must be saved as a PDF first, since Xero drops it. - Inbound route (ADR 0044 decision 2).
POST /receipts/inboundoutside Cloudflare Access, body limit 15 MiB, headersX-GetMy-Timestamp(unix seconds, within five minutes) andX-GetMy-Signature(hex HMAC-SHA256 of<timestamp>.<raw body>withRECEIPTS_INBOUND_SECRET, compared in constant time). The body is JSON:to,from,messageId,receivedAt,mime(base64 of the raw RFC 5322 message). A bad or stale signature is 400 with a value-free log line. The company is the one whose address isto(local part, case-insensitive), resolved insiderecord_receipt_email. The reply is JSON{ outcome, reply }wherereplyis the one-sentence text the Worker sends back to the sender; the route answers 200 for every verified message, including a rejected one, so the Worker does not retry. A store failure is 500 (the Worker retries) and a push alert with no identifiers. - Keeping files (decision 3). The MIME is parsed in memory. Attachments kept:
application/pdf,image/jpeg,image/png,image/heic,image/webp,image/tiff, except inline images under 20 KB (logos, signatures). Each kept file is uploaded to the Xero Files inbox withuploadFile(multipartPOST /files.xro/1.0/Fileswith no folder, which is the inbox), named<yyyy-mm-dd> <sender domain or supplier> <original name>made safe for a file name. When nothing is kept, the message is rendered to a PDF: the text and structure of the HTML part (headings, paragraphs, list items, table rows as aligned columns, links as their text followed by the URL), or the plain part, with every<img>, tracking pixel, script and style dropped and nothing fetched; the PDF names the sender, subject and date on its first lines; it is uploaded as<date> <sender domain> email.pdf. Bytes are never written to disk or the database. - Result for every email (decision 4). Outcomes:
filed(one or more files uploaded),duplicate(the samemessageIdfiled for this company, the same content hash filed, or every kept file's SHA-256 already recorded for this company; a repeat of amessageIdthat needs review gets that outcome and reply again, and uploads nothing),needs_review(the address is right but the message has no text and no kept attachment, or Xero refused the upload),rejected(unknown address, body over the limit, or no company for the address).receipt_emailholds: company, message id, content hash (SHA-256 over the kept files' hashes, or the rendered body text without its From, Subject and Date lines, so the same receipt forwarded again matches), sender, subject (cut to 200 characters), received at, outcome, reason, the Xero file ids and names uploaded, the parsed fields, and whether Xero refused. Unique on (company, message id). The reply text per outcome: "Filed in <company>'s Xero inbox as <name>. Ask Claude to reconcile it." / "Already filed on <date> as <name>." / "Received for <company> but nothing could be kept: <reason>. Forward the receipt as a PDF or ask Claude." / "Not filed: this address is not a GetMy Books receipts address." The reply goes only to the address the message came from, and names the file, never the receipt's figures, supplier or text (#407). Nothing is written to the activity log. - Parsing (decision 5).
parseReceiptEmailinsrc/rules/receipt-email.ts(pure) reads from the subject and text: supplier (the sender's display name or domain, or a "from"/"merchant" line), date (ISO, UK day-first dates, "14 Oct 2026"), total (the largest "Total" / "Amount paid" / "Grand total" figure; GBP and £ only,parseAmountToPence), VAT shown ("VAT", "Tax" lines;vatBreakdownShown), payment method (card, bank transfer, PayPal, Apple Pay) and the last four card digits ("ending 1234", "**** 1234"), a booking or order reference, and the evidence line for each value. Anything not found is left unset and listed as unparsed, never guessed. Any currency other than GBP setscurrencyand clears the amounts. - What Claude sees.
receipts_received(reads own records and Xero) lists a company's emails for a period or the last 30 days, newest first: outcome, sender, subject, files (Xero file ids and names), the parsed fields, and for eachfiledreceipt the proposed next step, decided byplanReceiptReconciliationagainst the company's purchase records within five days (attach),enter_firstwhen the owner names the bank account and a bank line fits,needs_billwhen nothing matched and the card is not one of the company's (matchCard; a bill from the director, SPEC-019 S17),not_ourswhen there were no figures to search with and the card is not the company's,no_matchotherwise; plus the VAT sense flags (slice 2d). The reconcile prompts look atreceipts_receivedbefore searching email. - Duplicates. By message id and by content hash at arrival (above), and by amount, date and supplier through
planReceiptReconciliation'sduplicateaction when two received receipts fit the same payment. - VAT sense checks (slice 2d, pure,
src/vat/receipt-vat-sense.ts). Flags on a parsed receipt: UK domestic flight or rail (zero-rated; the supplier or subject names an airline or rail operator, or the text names Air Passenger Duty), insurance (exempt), no VAT breakdown shown on a receipt whose supplier is normally standard-rated, VAT shown that is not a fifth of the net within a penny, and, for a company whose profile says not registered or registering (SPEC-020), "record the VAT shown in the pre-registration log instead of a VAT code". Flags are shown; nothing is coded from them. - Archive the original (slice 2f). The reconcile prompts offer, after a receipt is filed and attached, to archive the original email with the owner's own mail connector after the owner says yes. GetMy Books reads no mailbox (ADR 0031 amendment 1).
Design notes (slices 2c, 2d, 2f)
- Parser.
parseReceiptEmailreads the rendered body text (table rows as cells joined by " | ", lines cut to 500 characters). Amounts come from lines labelled Total, Grand total, Total paid, Amount paid or Amount charged (the largest figure on a line; unset when two lines differ), net from Subtotal or "excluding VAT" lines, VAT from VAT or Tax lines (not "VAT number") or "includes VAT of". A bare figure counts only when the email shows pounds and no other currency. Dates: a purchase-date label first, then a Date or Sent line, then the one date in the text, then the subject; two different dates at the same level leave it unset. The supplier: a Merchant or Supplier line, a forwarded block's From line, the sender's display name (not on a forward, whose sender is the forwarder), or the sender's domain name.receipt_email.parsedkeeps the fields,unparsedandmentions(the fixed words of travel the VAT checks use), never the evidence lines (S14). - receipts_received. The emails of the last 30 days or the period (received date), newest first, at most 50. Filed receipts with a total and a date in pounds go through
planReceiptReconciliation, oldest first so a later copy is the duplicate, against Xero's purchases 5 days either side of their dates (by amount and date; the supplier read from an email is not used to narrow, since it rarely equals the Xero contact). WithbankAccount(and the period), purchases are those paid from that account; with itscheckIdtoo, the check's bank lines giveenter_first. The emails are then those received from 5 days before the period through today (a receipt is often forwarded after month end), less any whose date, when read, is more than 5 days outside the period. A receipt that matches nothing, or has no figures, is checked withmatchCardon its last four digits:needs_billwhen nothing matched,not_ourswhen there were no figures to search with. It carries the read-outside annotations (it reads Xero). Five Xero reads for 50 receipts (tests/performance/budgets.ts,receiptsReceived). - VAT checks.
receiptVatFlagsinsrc/vat/receipt-vat-sense.ts; travel is matched on the supplier and subject (airlines, rail operators), and of the storedmentionsonly Air Passenger Duty counts ("train", "rail" and "flight" turn up in hotel and shop emails too); insurance bynoVatNatureon the supplier and subject only (a booking email often offers travel insurance). A receipt flagged as travel or insurance gets no other flag. For an unregistered company (SPEC-020 status not registered or registering) the pre-registration flag replaces the reclaim checks when VAT is shown; with no status in the profile it is unknown and changes nothing.
Out of scope
- Reading the owner's mailbox; sending email from GetMy Books itself (the Worker replies within the mail flow).
- Storing any file, email body or image; OCR of images; reading PDFs.
- Creating any Xero record from the parsed figures (ADR 0022 point 2; a bill from a received receipt is SPEC-019 with the owner's figures).
- Receipts in a currency other than GBP: filed, with the amounts left unset.
- Folders in Xero Documents (Xero ignores API folder moves, SPEC-005).
Data model sketch
inbound_address (entity_id uuid primary key references entity on delete cascade, local_part text not null unique, created_at, rotated_at); RLS for all policy as entity_profile; revoke delete (rotation replaces).
receipt_email (id uuid pk, entity_id uuid not null references entity on delete cascade, message_id text not null, content_hash text not null, from_address text not null, subject text null, received_at timestamptz not null, outcome text not null check in ('filed','duplicate','needs_review','rejected'), reason text null, files jsonb not null default '[]' (id, name, sizeBytes, sha256), parsed jsonb null (supplier, date, totalPence, vatPence, netPence, vatBreakdownShown, paymentMethod, cardLast4, reference, currency, unparsed), xero_refused boolean not null default false, created_at; unique (entity_id, message_id); index (entity_id, received_at desc)); RLS read-only policy as entity_subscription_read; revoke insert, update, delete from the app role; written by record_receipt_email(p_local_part, ...) (security definer, set search_path = pg_catalog, pg_temp, returns whether a company matched). Deleted with the company (cascade).
Integration sketch
| Call | Purpose | Scope or secret |
|---|---|---|
Cloudflare Email Routing: receipts.getmy.group catch-all to the Worker | Receive mail | Owner action |
Worker POST ${APP_URL}/receipts/inbound with HMAC headers | Hand the message to the app | RECEIPTS_INBOUND_SECRET |
POST /files.xro/1.0/Files (multipart, no folder: the inbox) | Upload the file | files (held; confirm by spike) |
GET /Invoices, GET /BankTransactions (existing readers) | Candidates for receipts_received | held |
Worker message.reply(...) | Tell the sender | n/a |
Settings: RECEIPTS_INBOUND_SECRET (64 hex), RECEIPTS_DOMAIN (receipts.getmy.group); both optional, both needed for the route and the address tool.
MCP tools sketch
| Tool | Read or write | Returns |
|---|---|---|
receipts_address | saves own memory; rotate replaces it (destructive, not idempotent) | The company's receiving address; a new one with rotate |
receipts_received | reads own records and Xero (read-outside) | Emails received for the company: outcome, files, parsed fields, proposed next step, VAT flags |
Scenarios
S1: The owner gets an address
Given a session with access to WEALTH TECH PROFESSIONALS LIMITED and the receipts settings set When receipts_address runs Then it returns <20 letters and digits>@receipts.getmy.group, the same on a second call, and a different one after rotate: true; the old one then rejects And a session without access to the company gets nothing Given the receipts settings are not set When receipts_address runs Then the reply is not an error: it says the GetMy receipts address is not switched on for this service yet, recommends the Xero Files inbox from receipts_inbox for receipts with a PDF or photo attached, says a body-only receipt must be saved as a PDF first, and issues nothing
S2: A signed message is accepted, an unsigned one is not
Given a POST with a valid signature over the timestamp and body When it arrives Then it is processed and answered 200 Given a missing, wrong or six-minutes-old signature, or a body over 15 MiB Then the reply is 400 or 413, nothing is parsed, and the log names no header value
S3: A PDF attachment is filed
Given a message to the company's address with a 90 KB PDF named "receipt.pdf" from receipts@supplier.com dated 2026-10-14 When it arrives Then one file "2026-10-14 supplier.com receipt.pdf" is uploaded to the company's Xero inbox, receipt_email holds outcome filed, the Xero file id and the SHA-256, and the reply is "Filed in WEALTH TECH PROFESSIONALS LIMITED's Xero inbox as 2026-10-14 supplier.com receipt.pdf. Ask Claude to reconcile it." And the reply names no total, supplier or date read from the receipt
S4: A body-only receipt is rendered and filed
Given the British Airways confirmation (HTML body, two tracking pixels, a logo image, no attachment) When it arrives Then a PDF named "2026-10-14 britishairways.com email.pdf" is uploaded whose text holds the subject, the sender, the date, the booking reference ZAJVFQ and "GBP 372.20", and no image or remote resource was fetched And the parsed fields hold supplier British Airways, total 37220 pence, reference ZAJVFQ, the date, and the card's last four digits if shown
S5: Small inline images are not receipts
Given a message with a 6 KB inline logo and a 300 KB JPEG photo of a receipt When it arrives Then only the JPEG is uploaded
S6: Duplicates are reported, not filed twice
Given S3 already filed When the same message id arrives again, or a different message whose only kept file has the same SHA-256, or the same body-only receipt forwarded again under a new message id and Date header Then nothing is uploaded, the outcome is duplicate, and the reply says when and as what it was filed
S7: An unknown address is rejected and the sender told
Given a message to nobody@receipts.getmy.group When it arrives Then nothing is uploaded or recorded against any company, the reply says it is not a GetMy Books receipts address, and the route still answers 200
S8: Xero refuses the upload
Given Xero answers 401 or 403 to the upload When a message arrives Then the outcome is needs_review with the reason, xero_refused is true, the reply tells the sender to ask Claude, and a push alert with no identifiers is sent once
S9: Claude sees what arrived and what to do
Given a filed receipt of 37220 pence from British Airways dated 2026-10-14 and a bill of £372.20 from British Airways dated 2026-10-14 in Xero without a file When receipts_received runs Then the receipt is listed with its file, the parsed fields, and the next step attach naming the bill, ready for attachments_preview And a receipt matching nothing with a card that is not the company's shows needs_bill; one matching nothing otherwise shows no_match
S10: Figures from a receipt are never written
Given any received receipt When any tool runs Then no Xero record carries a figure from the parsed fields; the only writes are the file upload and, after Approve, the attachment
S11: Companies are isolated
Given a session with access to FEAW only When receipts_received or receipts_address names WealthTechPros Then nothing is returned or changed, and FEAW's address never resolves to WealthTechPros
S12: The parser guesses nothing
Given an email whose text has no total, or a total in EUR, or two different "Total" lines When it is parsed Then the total is unset and listed as unparsed (or currency is EUR with amounts cleared), the evidence lines are kept, and the receipt is still filed
S13: VAT sense flags (slice 2d)
Given a filed BA receipt for a UK domestic flight with no VAT line, and a Hiscox insurance receipt, and a Dell receipt showing £20.00 VAT on £100.00 net When receipts_received runs Then the BA receipt is flagged "UK domestic flight: zero-rated, no VAT to reclaim", Hiscox "insurance: exempt", and Dell shows no flag; a company whose profile says registering sees "record the VAT shown in the pre-registration log" instead
S14: Nothing is stored but metadata
Given any processed message When processing completes or fails Then no file bytes, body text or image is in the database, logs or disk; receipt_email holds metadata, hashes and parsed fields only
S15: A new company gets its address when Xero is connected (#407)
Given an owner connecting a Xero organisation that is not yet a company in GetMy Books When the connection is saved Then the new company has a receipts address, and saving the connection again keeps the same address
S16: receipts_inbox recommends one address (#407)
Given WEALTH TECH PROFESSIONALS LIMITED has the GetMy address abcdefghij0123456789@receipts.getmy.group and the receipts settings are set When receipts_inbox runs Then the reply recommends that address as the one to forward receipts to, says it keeps a receipt that is just the email, and does not offer the Xero Files inbox address as an alternative Given the receipts settings are not set When receipts_inbox runs Then the reply recommends the Xero Files inbox address and says a receipt that is just the email must be saved as a PDF first
Edge cases
- Two companies' addresses in one message's recipients: each company's address is processed as its own message.
- A forwarded message wrapping the original: the outer sender is the owner; the parser prefers the "From:" line inside the forwarded block for the supplier.
- An attachment named
.pdfthat is not a PDF: Xero's refusal is recorded asneeds_review. - Mail larger than Cloudflare's limit never reaches the Worker; the owner guide says to forward the attachment only.
Dependencies
- ADR 0044; ADR 0031 as amended; ADR 0022 as amended; ADR 0032 (in memory only); ADR 0037 decision 4 (bypass route trusted by signature).
- SPEC-005 (
receipts_inbox,attachments_preview, matchers), SPEC-003 S34 (receipts_reconcile), SPEC-019 S17 (needs_bill), SPEC-020 (registration status). - Owner actions: Email Routing on the subdomain, the Worker and its secret, the Access Bypass application, Doppler prd settings, the root compose copy.
Exit test
Rob forwards the real British Airways confirmation and one PDF receipt to WEALTH TECH PROFESSIONALS LIMITED's GetMy address. Both appear in its Xero inbox as files; both replies arrive; receipts_received shows the BA receipt matched to the existing bill, and attaching it through the card works. Forwarding the BA email a second time gets the "already filed" reply.
Validation
| id | name | rule | assert |
|---|---|---|---|
| V1 | Signature only | Nothing is processed without a valid, fresh HMAC | S2 |
| V2 | A result for every email | Every verified message ends in one of four outcomes, recorded and replied | S3, S4, S6, S7, S8 |
| V3 | Nothing stored | No bytes, body or image kept anywhere | S14 |
| V4 | Figures are search terms | No parsed figure reaches Xero | S10, S12 |
| V5 | Address is the company | The address resolves to exactly one company; rotation revokes | S1, S7, S11, S15 |
| V7 | One address | Every reply showing an address recommends exactly one | S1, S16 |
| V8 | Reply names the file only | The sender's reply carries no figure or text read from the receipt | S3 |
| V6 | No fetch | Rendering fetches nothing from the internet | S4 |