Skip to content

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_address returns the company's receiving address to a signed-in owner with access to it, issuing one when none exists; receipts_address with rotate: true replaces it. The local part is 20 lower-case letters and digits from randomBytes; the domain is RECEIPTS_DOMAIN. Stored in inbound_address under 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 (from receipts_inbox), for receipts with a PDF or photo attached.
  • One address (#407). Every reply that shows an address recommends one. receipts_inbox recommends 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/inbound outside Cloudflare Access, body limit 15 MiB, headers X-GetMy-Timestamp (unix seconds, within five minutes) and X-GetMy-Signature (hex HMAC-SHA256 of <timestamp>.<raw body> with RECEIPTS_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 is to (local part, case-insensitive), resolved inside record_receipt_email. The reply is JSON { outcome, reply } where reply is 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 with uploadFile (multipart POST /files.xro/1.0/Files with 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 same messageId filed for this company, the same content hash filed, or every kept file's SHA-256 already recorded for this company; a repeat of a messageId that 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_email holds: 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). parseReceiptEmail in src/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 sets currency and 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 each filed receipt the proposed next step, decided by planReceiptReconciliation against the company's purchase records within five days (attach), enter_first when the owner names the bank account and a bank line fits, needs_bill when nothing matched and the card is not one of the company's (matchCard; a bill from the director, SPEC-019 S17), not_ours when there were no figures to search with and the card is not the company's, no_match otherwise; plus the VAT sense flags (slice 2d). The reconcile prompts look at receipts_received before searching email.
  • Duplicates. By message id and by content hash at arrival (above), and by amount, date and supplier through planReceiptReconciliation's duplicate action 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. parseReceiptEmail reads 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.parsed keeps the fields, unparsed and mentions (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). With bankAccount (and the period), purchases are those paid from that account; with its checkId too, the check's bank lines give enter_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 with matchCard on its last four digits: needs_bill when nothing matched, not_ours when 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. receiptVatFlags in src/vat/receipt-vat-sense.ts; travel is matched on the supplier and subject (airlines, rail operators), and of the stored mentions only Air Passenger Duty counts ("train", "rail" and "flight" turn up in hotel and shop emails too); insurance by noVatNature on 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 ​

CallPurposeScope or secret
Cloudflare Email Routing: receipts.getmy.group catch-all to the WorkerReceive mailOwner action
Worker POST ${APP_URL}/receipts/inbound with HMAC headersHand the message to the appRECEIPTS_INBOUND_SECRET
POST /files.xro/1.0/Files (multipart, no folder: the inbox)Upload the filefiles (held; confirm by spike)
GET /Invoices, GET /BankTransactions (existing readers)Candidates for receipts_receivedheld
Worker message.reply(...)Tell the sendern/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 ​

ToolRead or writeReturns
receipts_addresssaves own memory; rotate replaces it (destructive, not idempotent)The company's receiving address; a new one with rotate
receipts_receivedreads 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 .pdf that is not a PDF: Xero's refusal is recorded as needs_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 ​

idnameruleassert
V1Signature onlyNothing is processed without a valid, fresh HMACS2
V2A result for every emailEvery verified message ends in one of four outcomes, recorded and repliedS3, S4, S6, S7, S8
V3Nothing storedNo bytes, body or image kept anywhereS14
V4Figures are search termsNo parsed figure reaches XeroS10, S12
V5Address is the companyThe address resolves to exactly one company; rotation revokesS1, S7, S11, S15
V7One addressEvery reply showing an address recommends exactly oneS1, S16
V8Reply names the file onlyThe sender's reply carries no figure or text read from the receiptS3
V6No fetchRendering fetches nothing from the internetS4