How do I track direct mail and promotional package deliveries by API?

Watch each tracked mailer, sample box or gift with the campaign in metadata. A webhook on delivery lets you time the follow-up email or call to the day the piece arrived, and a short script over GET /v1/watches counts how many pieces in each campaign are delivered, still moving or stuck. This covers pieces sent with a carrier tracking number; untracked letter mail and Intelligent Mail barcodes are not tracked. Pro is $4.99/mo for 1,000 unique numbers, then $0.015 each, with no daily limit. A free key tracks 5 numbers a day. With no key you get 1 lookup a day, then pay per request over MPP: $0.50 by card for a 25-number pack, or $0.02 a number in USDC on Tempo.

Try it

curl: watch a campaign's pieces
curl -X POST https://api.lastscanned.com/v1/watches \
  -H "Authorization: Bearer lsk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"trackingNumbers": ["1Z000Y770414233027", "541270563758"], "metadata": {"campaign": "q4-mailer"}}'
Node: count watched pieces by campaign
const counts = {};
let cursor;
do {
  const url = new URL("https://api.lastscanned.com/v1/watches");
  url.searchParams.set("limit", "100");
  if (cursor) url.searchParams.set("cursor", cursor);
  const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.LASTSCANNED_KEY}` } });
  const page = await res.json();
  for (const w of page.watches) {
    const campaign = w.metadata?.campaign ?? "none";
    const status = w.result?.status ?? "pending";
    (counts[campaign] ??= {})[status] = (counts[campaign][status] ?? 0) + 1;
  }
  cursor = page.nextCursor;
} while (cursor);
console.table(counts);

Ways to know when campaign pieces arrive

OptionHow it worksPriceNotes
Guess from ship dateAssume delivery a few days after sending.FreeFollow-ups land before or long after the piece.
Batch the campaign listSend the campaign's numbers 35 per request and count statuses.On Pro re-checks are freeA snapshot when you run it.
Watches + webhookPOST /v1/watches with the campaign in metadata; follow up on delivered.Each piece counts onceAny of 549 carriers.

Details

Follow up on arrival

A tracking.updated event with status delivered carries your campaign metadata and deliveredAt, so the follow-up goes out the day the piece lands.

Pieces that never arrive

Exceptions and returns arrive as events too. A piece returned to sender usually means a bad address to fix before the next send.

What is and isn't covered

Any piece with a carrier tracking number: USPS, UPS, FedEx and regional carriers. Untracked letter mail and Intelligent Mail barcodes are not.

What it costs

1,500 tracked pieces in a month is $4.99 + 500 × $0.015 = $12.49, with every re-check free.

FAQ

Can I tag tracking numbers by campaign?
Yes. Put the campaign in metadata (up to 2 KB of JSON) and it comes back on every webhook and in GET /v1/watches.
Does this track postcards and letters?
Only pieces with a carrier tracking number. Untracked mail has no scans to read.
How many pieces can one campaign have?
Up to 5,000 active watches per account, added up to 100 per call.
Can I time follow-ups to delivery?
Yes. Send the follow-up from your tracking.updated handler when status is delivered.