Quickstart

From nothing to a booked, tracked test shipment in the sandbox. Nothing here is real and no money moves.

1. Create an application and a sandbox key

Sign in to EviPostal, open Developers → Applications and create an application. Then open API keys, keep Sandbox selected and create a key. The secret is shown once: copy it into an environment variable on your machine.

Terminal

export EVIPOSTAL_API_KEY="evp_test_…"   # paste your sandbox secret key here

2. Check the key

GET /me says which business, application and environment the key belongs to.

curl "https://api.evipostal.com/v1/me" \
  -H "Authorization: Bearer $EVIPOSTAL_API_KEY"

3. Get rates

Send who is sending, who is receiving and the package. Rates come back cheapest first, each with an id you can book until expires_at.

curl -X POST "https://api.evipostal.com/v1/rates" \
  -H "Authorization: Bearer $EVIPOSTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": {
      "name": "Ada Okafor",
      "phone": "+2348031234567",
      "email": "orders@example.com",
      "line1": "12 Allen Avenue",
      "city": "Ikeja",
      "state": "Lagos",
      "country": "NG"
    },
    "to": {
      "name": "Chinedu Obi",
      "phone": "+2348097654321",
      "email": "chinedu@example.com",
      "line1": "5 Admiralty Way",
      "city": "Lekki",
      "state": "Lagos",
      "country": "NG",
      "landmark": "Opposite the filling station"
    },
    "parcels": [
      {
        "package_type": "box",
        "weight_grams": 1500,
        "length_cm": 30,
        "width_cm": 20,
        "height_cm": 10,
        "description": "Two pairs of shoes",
        "declared_value": 4500000
      }
    ],
    "reference": "order-1042",
    "metadata": {
      "order_id": "1042"
    }
  }'

4. Book a rate

Replace rate_… below with an id from your step 3 response. Send an Idempotency-Key header: a name you choose for this one booking. If the request is retried with the same key, the shipment is still booked only once (why this matters). Use a new key for every new booking: the same key with a different rate is refused with idempotency_key_reused.

curl -X POST "https://api.evipostal.com/v1/shipments" \
  -H "Authorization: Bearer $EVIPOSTAL_API_KEY" \
  -H "Idempotency-Key: order-1042-booking-1" \
  -H "Content-Type: application/json" \
  -d '{
    "rate_id": "rate_7Qm2Lx9KaP3sT8vB1nW4cY6d"
  }'

5. Download the label and follow the tracking

Use the id (shp_…) from your step 4 response. Sandbox shipments move on their own, so there is soon something to read.

curl "https://api.evipostal.com/v1/shipments/shp_7Hk2Lq9Wm3Xz5Rt8Yb1Nc4Vd/label" \
  -H "Authorization: Bearer $EVIPOSTAL_API_KEY" \
  -o label.pdf

curl "https://api.evipostal.com/v1/shipments/shp_7Hk2Lq9Wm3Xz5Rt8Yb1Nc4Vd/tracking" \
  -H "Authorization: Bearer $EVIPOSTAL_API_KEY"

6. Receive webhooks

Add an endpoint (an https address on your server) in Developers → Webhooks or with the API, then press Send test event. Check the signature of every message: here is the code.

curl -X POST "https://api.evipostal.com/v1/webhook-endpoints" \
  -H "Authorization: Bearer $EVIPOSTAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://shop.example.com/webhooks/evipostal",
    "description": "Order updates",
    "event_types": [
      "shipment.booked",
      "shipment.delivered",
      "shipment.exception"
    ]
  }'

Test failures on purpose with the sandbox scenarios.
Handle every error code.
When it all works, request production access from the Developers overview.