YunExpress Tracking API & MCP

Query live YunExpress (yunexpress, 云途物流 / YunTrack) cross-border package status, scan history, and domestic last-mile handoff numbers in a single synchronous GET request or MCP tool call. lastscanned auto-detects 18-character YT… waybills and returns a normalized TrackingResult JSON payload—without requiring a YunExpress customer number or API secret.

Overview & Quick FactsCopy Anchor Link

Why developers use lastscanned for YunExpress instead of direct requestsCopy Anchor Link

• Avoid Alibaba Cloud WAF 405 blocks & 30-minute IP bans: Direct requests from Cloudflare Workers, Vercel, or AWS Lambda to services.yuntrack.com are blocked by Alibaba Cloud's web application firewall (acw_tc / 405 Method Not Allowed), which issues 30-minute IP bans on automated datacenter traffic. Calling GET https://api.lastscanned.com/v1/track/:number from your backend returns clean JSON in one fetch().
• Automatic last-mile carrier & exchange number extraction: YunExpress hands US and Canadian parcels to USPS, UniUni, GOFO Express, OnTrac, or FedEx. lastscanned extracts both the last-mile carrier name (AdditionalNotes) and secondary tracking number (TrackInfo.TrackingNumber) into top-level message (e.g. "Handed to GOFO Express as GFUS01074503026309").

Tracking Number Formats & Auto-Detection (matches vs mayMatch)Copy Anchor Link

YunExpress is evaluated eighteenth (#18) in lastscanned's two-pass detector:

When is ?carrier=yunexpress optional vs required?Copy Anchor Link

• Optional (auto-detected): All 18-character YT + 16-digit tracking numbers auto-detect in Pass 1. No other carrier uses the YT prefix.
• Required (?carrier=yunexpress): Customer order reference numbers or last-mile exchange numbers that you want to query inside YunTrack instead of the domestic last-mile carrier.

Synchronous GET Request & Normalized JSON ResponseCopy Anchor Link

curlCopy Anchor Link

curl -s "https://api.lastscanned.com/v1/track/YT2604521272152698" \
  -H "Authorization: Bearer $LASTSCANNED_API_KEY"

JavaScript / TypeScript (fetch)Copy Anchor Link

const res = await fetch("https://api.lastscanned.com/v1/track/YT2604521272152698", {
  headers: { Authorization: `Bearer ${process.env.LASTSCANNED_API_KEY}` },
});
const pkg = await res.json();
console.log(pkg.status, pkg.service, pkg.message);

MCP track_package tool callCopy Anchor Link

{
  "tool": "track_package",
  "arguments": {
    "tracking_number": "YT2604521272152698"
  }
}

Normalized TrackingResult JSON responseCopy Anchor Link

{
  "carrier": "yunexpress",
  "trackingNumber": "YT2604521272152698",
  "status": "delivered",
  "statusDescription": "Delivered",
  "service": "YunExpress Standard",
  "deliveredAt": null,
  "deliveredAtLocal": "2026-10-25T13:42:11",
  "signedBy": null,
  "destination": {
    "city": null,
    "state": null,
    "country": "US"
  },
  "estimatedDelivery": null,
  "message": "Handed to GOFO Express as GFUS01074503026309",
  "events": [
    {
      "timestamp": null,
      "localTime": "2026-10-25T13:42:11",
      "status": "delivered",
      "description": "Delivered",
      "location": "EDISON, NJ",
      "code": null
    },
    {
      "timestamp": null,
      "localTime": "2026-10-25T08:15:08",
      "status": "out_for_delivery",
      "description": "Out for delivery",
      "location": "EDISON, NJ",
      "code": null
    },
    {
      "timestamp": null,
      "localTime": "2026-10-22T19:30:00",
      "status": "in_transit",
      "description": "Arrived at destination airport",
      "location": "JFK, US",
      "code": null
    },
    {
      "timestamp": null,
      "localTime": "2026-10-19T11:04:22",
      "status": "label_created",
      "description": "Shipment information received",
      "location": "SHENZHEN",
      "code": null
    }
  ]
}

Chaining Last-Mile Handoffs (message)Copy Anchor Link

Because YunExpress prints scan times in each facility's local clock without a UTC offset (timestamp: null, localTime populated) and only reports country-level destination.country, chaining the last-mile tracking number from message gives you even richer data:

1. Check pkg.message on the YunExpress response (for example, "Handed to GOFO Express as GFUS01074503026309" or "Handed to USPS as 9261290312839104827163").
2. Extract the trailing tracking number and call GET https://api.lastscanned.com/v1/track/GFUS01074503026309.
3. Receive exact UTC timestamp values, destination city/state, and doorstep delivery details from the domestic carrier.

Carrier-Specific Status & Integration NotesCopy Anchor Link

• YunExpress PackageState mapping: YunExpress numeric package states map deterministically to normalized statuses: 3, 4, 17 → delivered; 19 → out_for_delivery; 7, 8, 10, 15 → returned; 2, 6, 9, 11, 12, 13, 14, 16 → exception; 1, 5, 18 → in_transit (or label_created when only "Shipment information received" exists).

Related ResourcesCopy Anchor Link

• Live browser lookup tool: Track a YunExpress package live on lastscanned.com/lookup/yunexpress
• Carrier hub: All 31 supported carriers
• Regex & check digits: Tracking number formats & auto-detection
• AI support workflows: WISMO AI agents & synchronous tracking