Track deliveries
mxr watches incoming mail for shipping notifications, collapses the many emails of one order (confirmation → shipped → out for delivery → delivered) into a single tracked delivery, and shows you what’s on the way. Detection runs automatically as mail syncs — you browse and manage the results.
How detection works
Section titled “How detection works”Three stages, all local-first:
- Heuristic shortlist — a deterministic, offline pass over each new message: carrier/merchant senders, shipping subject lines, schema.org
ParcelDelivery/Ordermarkup, and checksum-validated tracking numbers (UPS, FedEx, USPS, DHL, Amazon, S10 international, …). - LLM confirm + extract (optional) — shortlisted-but-uncertain candidates go to your configured LLM to confirm it’s really a shipment and pull out merchant, carrier, items, and ETA. An ETA comes only from words the email itself uses (such as “arriving Thursday”), resolved against the day the email was sent, so the model never writes a date. Any tracking number the model returns is re-checked against the checksum library before it’s trusted.
- Lifecycle — emails are correlated (by tracking number, then merchant + order number) into one delivery whose status only ever advances. A “delivered” email resolves it automatically.
It optimizes for precision: a string that merely looks like a tracking number inside an unrelated email (a finance code, a hosting receipt) won’t create a delivery on its own — it needs a real shipping signal or LLM confirmation.
See what’s arriving
Section titled “See what’s arriving”mxr deliveries listWhat you get: a table of in-flight deliveries (status, merchant, carrier, ETA, tracking number), newest activity first. Already-delivered and dismissed rows are hidden.
Switch the slice with --filter:
mxr deliveries list --filter delivered # resolved, recentmxr deliveries list --filter all # everything except dismissedmxr deliveries list --filter dismissed # false positives you hidInspect one delivery
Section titled “Inspect one delivery”mxr deliveries --format json get DELIVERY_IDWhat you get: the full record — merchant, carrier, tracking_number, tracking_url, order_number, status, eta_until, items, confidence, source (schema / llm / heuristic), and message_ids (the source emails that built it).
Get a delivery’s id from mxr deliveries --format json list.
Resolve or dismiss
Section titled “Resolve or dismiss”A delivery resolves itself when a “delivered” email arrives. Close one out by hand, or hide a false positive:
mxr deliveries resolve DELIVERY_ID # mark delivered/done; leaves the active listmxr deliveries dismiss DELIVERY_ID # hide a misfire; kept under --filter dismissedBoth are single-row, non-destructive — the row and its provenance are retained.
A parcel with no news goes quiet and leaves the active list
Section titled “A parcel with no news goes quiet and leaves the active list”A parcel that stops sending news is not in transit forever. Seven days
past its latest arrival date, or 14 days after its last event when it has
no arrival date, it goes quiet: --filter active no longer lists it, and
--filter all still does. Updates shows one “went quiet” line in the
digest after it happens, then lets it go.
Parcels are trackers in Updates
Section titled “Parcels are trackers in Updates”Updates shows each parcel’s current status, any available
item name and tracking or order reference, and its estimate. An earliest-only
estimate is labelled “Expected from”; a latest-arrival estimate is labelled
“Expected by”. In the web app, Details reveals all available item records,
references and the reason for the update; From email opens its source message.
Pickup and delivery problems are named in the status. A parcel that moved
since the last digest is under Changed; one that didn’t is routine. A
delivered parcel shows for a day, then leaves on its own. A delivery problem,
a failed attempt or a return goes under Needs a look for a week. The line
explains when mxr cannot verify the receiver’s sender verdict; t adds the
suggested to-do. Current live adapters hold automatic alert creation.
See Updates.
Backfill existing mail
Section titled “Backfill existing mail”Detection only sees new mail going forward. Catch up on what’s already in your store, previewing first:
# Preview only — no writes, no LLM calls:mxr deliveries scan --since-days 90 --dry-runWhat you get: { "scanned": 941, "created": 23, "updated": 0, "shortlisted": 44, "dry_run": true } — how many messages were examined, how many deliveries a real run would create, and how many would be sent to the LLM.
Then run it for real (the LLM step makes it slower over wide windows, so it streams to completion rather than timing out):
mxr deliveries scan --since-days 90In real life
Section titled “In real life”- What’s arriving this week, soonest first:
mxr deliveries --format json list | jq -r 'map(select(.eta_until)) | sort_by(.eta_until) | .[] | "\(.eta_until[0:10])\t\(.merchant // .carrier)\t\(.status)"'— a date-sorted arrival board. - Which orders shipped but haven’t landed:
mxr deliveries --format json list --filter active | jq -r '.[] | select(.tracking_number) | "\(.merchant)\t\(.tracking_number)"'— merchant + tracking for everything in transit. - Audit detection before trusting it:
mxr deliveries scan --since-days 30 --dry-run— see the create/shortlist counts on a known window without writing a thing. - Clear a stale misfire:
mxr deliveries dismiss DELIVERY_ID— hides one bad row without affecting the email.
Agent prompts that work
Section titled “Agent prompts that work”"Run `mxr deliveries --format json list` and tell me which packages arearriving in the next 3 days, with merchant and carrier. Don't resolve ordismiss anything — just report.""Use `mxr deliveries --format json list --filter active` to find anydelivery whose ETA has already passed but isn't marked delivered, andlist its merchant, tracking number, and source email ids from`mxr deliveries get <id>`."Delivered orders become records in Archive
Section titled “Delivered orders become records in Archive”When a delivery reaches delivered, its order is filed in
Archive as an order record, with the delivery date and
the delivery’s emails as sources. If the shop’s own emails already filed
that order number, the delivery joins that record rather than adding a
second one, so the confirmation, dispatch and delivery are one row. A
delivery with no order number becomes a record of its own. The tracker in
mxr deliveries stays as it was.
mxr records list --kind orderIn the apps
Section titled “In the apps”- TUI: press
gthenPfor the Deliveries tab.j/kto move,o/Enterto open the source email inline in a split preview (Ctrl-d/Ctrl-uscroll it,Esccloses it),rto resolve,dto dismiss,Dto cycle the active/delivered/all filter,Rto refresh. Opening the source email is handy for inspecting a false positive — e.g. a phishing “DHL” mail misread as a shipment — before dismissing it. See keybindings. - Web: the Deliveries page in the sidebar shows the same list with resolve/dismiss buttons and a link to each delivery’s thread. See Web app.
See also
Section titled “See also”- LLM features — the optional confirm-and-extract step and how to configure it
- Config — the
[deliveries]section and thedelivery_extractionLLM override - CLI: deliveries — every flag
- Security & privacy — detection is local; nothing is sent to carriers