Agentic development skill for building, debugging, and extending integrations with the EasyPost shipping API.
This repository provides structured knowledge and runnable examples for working with EasyPost. It covers the full shipping workflow: addresses, parcels, rates, labels, customs, tracking, pickups, scan forms, batches, insurance, claims, reports, webhooks, and carrier-specific gotchas.
This is a multi-skill repository. Each top-level directory represents an independent skill that can be used individually or together:
├── easypost-api/ # Core EasyPost API skill
│ ├── SKILL.md # Skill definition and routing table
│ ├── references/ # Detailed reference documentation
│ └── scripts/ # Runnable Node.js examples
└── README.md # This file
| Skill | Description |
|---|---|
easypost-api |
Build, debug, and extend EasyPost shipping API integrations |
Load the skill directory into your agentic development environment. The SKILL.md file in each skill directory provides the entry point, routing table, and conventions.
The easypost-api/scripts/ directory contains runnable Node.js examples:
cd easypost-api
npm install @easypost/api
# Set your API key
export EASYPOST_API_KEY="your_test_key_here"
# Run an example
node scripts/create-shipment.mjscreate-shipment.mjs— Address → parcel → shipment → buy lowest rate → save label PDFverify-address.mjs— Address verification withcreateAndVerifyinternational-shipment.mjs— Customs info + items + shipment with tax identifiertrack-shipment.mjs— Create tracker, poll statuswebhook-handler.mjs— Express endpoint usingclient.Utils.validateWebhookbatch-buy.mjs— Create batch, add shipments, purchase, generate combined labelschedule-pickup.mjs— Create pickup, buy cheapest pickup ratesmartrate-deliver-by.mjs— Pick cheapest rate meeting a delivery deadline
- Always use a test API key during development. Production keys cost real money on every label purchase.
- Inspect
shipment.messageswhen rates are missing. Carriers that failed to rate return a message instead of a rate. - Customs info is required for international shipments. Build
CustomsInfowith accurate HS tariff numbers. - Do not trust
lowestRate()blindly for international or time-critical shipments. Use SmartRate or Luma when delivery guarantees matter. - Verify webhook HMAC signatures with
client.Utils.validateWebhook(). - Label URLs expire. Download the PDF/PNG to your own storage immediately after purchase.
- Node.js 18+
- An EasyPost account (free tier available)
- Test API key for development
This skill is maintained for agentic development workflows. Improvements to accuracy, coverage, and clarity are welcome.
MIT