Overview

Partner integration surface for programmatic access to MailHub's order and shipment management platform.

Base URL & Versioning

Base URL	`https://api.example.com/api`
Version	`v1`
Content-Type	`application/json` (all endpoints unless noted)

All paths in this documentation are relative to the base URL. For example, POST /v1/auth/token means POST https://api.example.com/api/v1/auth/token.

Quick Start

Step 1 — Get your API key from the MailHub partner dashboard.

Step 2 — Authenticate. Exchange your API key for a Bearer token:

curl -X POST https://api.example.com/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "your_api_key_here"}'

Step 3 — Make requests using the accessToken from the response:

curl -X POST https://api.example.com/api/v1/orders \
  -H "Authorization: Bearer <accessToken>" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

Endpoint Overview

Authentication

Method	Path	Description	Auth
POST	`/v1/auth/token`	Login — exchange API key for tokens	API Key
POST	`/v1/auth/token/refresh`	Refresh an expired access token	Refresh Token
POST	`/v1/auth/token/revoke`	Revoke a refresh token (logout)	Refresh Token

Orders

Method	Path	Description	Auth
POST	`/v1/orders`	Create an order	Bearer
PATCH	`/v1/orders/{orderId}/status`	Update order status	Bearer
GET	`/v1/orders`	List orders (paginated, filterable)	Bearer
GET	`/v1/orders/{orderId}`	Get a single order by ID	Bearer

V2 Orders

Method	Path	Description	Auth
POST	`/v2/orders`	Create an order and return shipment rates	Bearer

Shipments

Method	Path	Description	Auth
POST	`/v1/shipments/{shipmentId}/rates`	Get carrier rate quotes	Bearer
POST	`/v1/shipments/{shipmentId}/labels`	Buy a shipping label	Bearer

Labels

Method	Path	Description	Auth
GET	`/v1/labels/{labelId}/download`	Download label file (PDF/ZPL/EPL2)	Bearer
DELETE	`/v1/labels/{labelId}`	Cancel (void) a label	Bearer

Typical Integration Flow

1. Authenticate
   POST /v1/auth/token  →  receive accessToken + refreshToken

2. Create order
   POST /v1/orders  →  receive orderId + shipmentId
                        (order status: Created)

3. Update order status to Packed
   PATCH /v1/orders/{orderId}/status  →  set status to 7 (Packed)
   ⚠️  Order must be in Packed status before you can get rates or buy labels.

4. Get rates
   POST /v1/shipments/{shipmentId}/rates  →  compare carrier quotes

5. Buy label
   POST /v1/shipments/{shipmentId}/labels  →  receive labelId + trackingCode

6. Download label
   GET /v1/labels/{labelId}/download  →  print and ship

7. Update order status to Fulfilled
   PATCH /v1/orders/{orderId}/status  →  set status to 4 (Fulfilled)

   If needed: cancel the label before shipping
   DELETE /v1/labels/{labelId}  →  void the label

Alternative — Create with rates (V2): If you want to create an order and fetch its shipment rates in a single call, use POST /v2/orders instead of steps 2 and 4. It creates the order and returns the rates per shipment in one response. See the V2 Orders section for details.

Optional Headers

Header	Type	Description
`X-SubAccount-Id`	uuid	Optional. Scopes the request to a specific sub-account. When omitted, the request operates at the account level.

See the Sub-Accounts section for full details.

General Notes

All timestamps are UTC in ISO 8601 format (e.g. 2026-04-02T19:30:00Z).
All resource identifiers are UUIDs.
Rate and price values are returned as decimals. The rate field in the selectedRate object on the Buy Label response is returned as a string to preserve formatting.
The /v1 API does not support batch operations — one order per request. Use /v2/orders to create an order and fetch its rates together.
Request and response bodies use camelCase field names.