Authenticate via OAuth 2.0 by POSTing to https://apis.usps.com/oauth2/v3/token with your client credentials to get a bearer token
GET https://apis.usps.com/tracking/v3/tracking/{trackingNumber} with the USPS tracking number as a path parameter; include the expand=DETAIL query parameter to receive full event history
Parse the trackSummary and trackDetail arrays from the response for event descriptions, timestamps, and locations
For proactive notifications, call GET https://apis.usps.com/tracking/v3/tracking/{trackingNumber}?expand=SUMMARY&revisedDeliveryDate=true to check for estimated delivery date updates
Handle HTTP 404 responses gracefully: USPS tracking numbers are not activated in the system until the package's first acceptance scan, so early queries legitimately return not found
Implement exponential backoff when polling: USPS tracking data typically updates at scan events, not continuously
Known gotchas
The USPS Web Tools TrackV2 XML endpoint was retired with the full Web Tools platform in January 2026; all tracking integrations must use the REST API at apis.usps.com/tracking/v3/
USPS tracking numbers are not guaranteed to be unique across all time; reusing a tracking number from an old shipment in queries may return stale historical data for the previous shipment
USPS does not provide real-time GPS location data; tracking events are scan-based and may show gaps of many hours between updates for packages in transit between sorting facilities
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