Track a parcel across multiple carriers using a unified tracking API and normalize divergent carrier event codes into a canonical delivery state machine
Create a Tracker via POST /v2/trackers with the tracking_code and carrier fields; if carrier is unknown, omit it and EasyPost will attempt carrier detection from the tracking number format
Subscribe to tracking webhook events at the /v2/webhooks endpoint with event_type TRACKER_UPDATED; each inbound event contains a Tracker object with the current status field and a tracking_details array of events
Map the EasyPost status field to your canonical states: pre_transit, in_transit, out_for_delivery, delivered, available_for_pickup, return_to_sender, failure, error, and unknown; build a strict state machine that only allows forward state transitions to prevent out-of-order events from rolling back a delivered status
Extract the carrier-reported tracking_details[].message and tracking_details[].tracking_location for display; these are the raw carrier scan messages and locations, not normalized
For delivered events, capture the signed_by field if present (available for signature-required services) and the est_delivery_date from the most recent delivery event
Implement webhook idempotency using the webhook object id field; store processed event IDs in Redis or a database and reject reprocessing if the ID has already been seen
Known gotchas
EasyPost webhook delivery is at-least-once; under high load or after retries, the same tracking event may be delivered multiple times; idempotency on the tracker update event object id is mandatory to prevent duplicate status transitions
The EasyPost status unknown is returned when the carrier has not yet accepted the package into their system (label printed but not scanned); displaying unknown to end customers causes unnecessary support contacts; substitute a pre_transit label until the first carrier scan event
Some carriers (particularly regional carriers and postal services) report tracking_code formats that overlap with other carriers; if EasyPost auto-detects the wrong carrier, it will subscribe to the wrong carrier's tracking feed and return no tracking updates; always provide explicit carrier when known
Give your agent this knowledge — and 200+ more routes
One MCP install gives any agent live access to the full route map, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp