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 -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"}}'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
| Option | How it works | Price | Notes |
|---|---|---|---|
| Guess from ship date | Assume delivery a few days after sending. | Free | Follow-ups land before or long after the piece. |
| Batch the campaign list | Send the campaign's numbers 35 per request and count statuses. | On Pro re-checks are free | A snapshot when you run it. |
| Watches + webhook | POST /v1/watches with the campaign in metadata; follow up on delivered. | Each piece counts once | Any 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.