Skip to content

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.

Three stages, all local-first:

  1. Heuristic shortlist — a deterministic, offline pass over each new message: carrier/merchant senders, shipping subject lines, schema.org ParcelDelivery/Order markup, and checksum-validated tracking numbers (UPS, FedEx, USPS, DHL, Amazon, S10 international, …).
  2. 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.
  3. 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.

Terminal window
mxr deliveries list

What 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:

Terminal window
mxr deliveries list --filter delivered # resolved, recent
mxr deliveries list --filter all # everything except dismissed
mxr deliveries list --filter dismissed # false positives you hid
Terminal window
mxr deliveries --format json get DELIVERY_ID

What 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.

A delivery resolves itself when a “delivered” email arrives. Close one out by hand, or hide a false positive:

Terminal window
mxr deliveries resolve DELIVERY_ID # mark delivered/done; leaves the active list
mxr deliveries dismiss DELIVERY_ID # hide a misfire; kept under --filter dismissed

Both 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.

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.

Detection only sees new mail going forward. Catch up on what’s already in your store, previewing first:

Terminal window
# Preview only — no writes, no LLM calls:
mxr deliveries scan --since-days 90 --dry-run

What 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):

Terminal window
mxr deliveries scan --since-days 90
  • 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.
"Run `mxr deliveries --format json list` and tell me which packages are
arriving in the next 3 days, with merchant and carrier. Don't resolve or
dismiss anything — just report."
"Use `mxr deliveries --format json list --filter active` to find any
delivery whose ETA has already passed but isn't marked delivered, and
list 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.

Terminal window
mxr records list --kind order
  • TUI: press g then P for the Deliveries tab. j/k to move, o/Enter to open the source email inline in a split preview (Ctrl-d/Ctrl-u scroll it, Esc closes it), r to resolve, d to dismiss, D to cycle the active/delivered/all filter, R to 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.
  • LLM features — the optional confirm-and-extract step and how to configure it
  • Config — the [deliveries] section and the delivery_extraction LLM override
  • CLI: deliveries — every flag
  • Security & privacy — detection is local; nothing is sent to carriers