Make Your First Request

Exchange your API key for an access token, then list Orders. GET /api/v1/orders does not create an Order, retrieve rates, or purchase a Label, so it is the safe first public call for an account with no Orders yet.

1. Exchange your API key

POST/api/v1/auth/token Open token exchange in the API Reference.

Follow Authentication and Token Lifecycle to exchange MAILHUB_API_KEY for an access token. Retain the returned access and refresh tokens securely; the API key itself is not a Bearer token.

2. List Orders

GET/api/v1/orders Open list orders in the API Reference.

GET /api/v1/orders uses Bearer authentication. Its search, date range, statuses, pagination, and sorting parameters are optional.

Optional scope and query parameters

pageNumber, pageSize, and sortByNewest are optional. X-SubAccount-Id is also optional: when present on List Orders, it filters the response to that authorized Sub-account; when omitted, the Account is the default context.

cURL

curl -s "${MAILHUB_API_BASE_URL}/api/v1/orders" \
-H "Authorization: Bearer ${MAILHUB_ACCESS_TOKEN}"

JavaScript

const response = await fetch(`${process.env.MAILHUB_API_BASE_URL}/api/v1/orders`, {
headers: {Authorization: `Bearer ${process.env.MAILHUB_ACCESS_TOKEN}`},
});

const {data: page} = await response.json();
// page.items, page.totalItemsCount, page.pageNumber, page.pageSize

Java

// Java 11+ java.net.http — no Mailhub package to install and no third-party client.
var request = HttpRequest.newBuilder()
  .uri(URI.create(System.getenv("MAILHUB_API_BASE_URL") + "/api/v1/orders"))
  .header("Authorization", "Bearer " + System.getenv("MAILHUB_ACCESS_TOKEN"))
  .GET()
  .build();

HttpResponse<String> response = HttpClient.newHttpClient()
  .send(request, HttpResponse.BodyHandlers.ofString());

// Parse response.body() with your own JSON library:
// data.items, data.totalItemsCount, data.pageNumber, data.pageSize

A successful response is a paged public envelope. An empty items array is a successful result for a newly prepared Account.

{
  "success": true,
  "data": {
    "items": [],
    "totalItemsCount": 0,
    "pageNumber": 1,
    "pageSize": 20,
    "totalPages": 0,
    "hasNext": false,
    "hasPrevious": false
  },
  "errors": null
}

Common authentication and scope errors

• 401 means the Bearer token is missing, invalid, or no longer accepted; follow the one-refresh-then-re-authenticate flow.
• 403 means the authenticated Account is not authorized for the request.
• 422 can indicate an invalid optional query value. Check the API Reference before retrying with changed input.
• For Sub-account header validation details, including malformed or inactive values, see Authentication and Token Lifecycle.

Next step

Continue to Create an Order only when your workflow is ready to create state. Review the Order-to-Label Workflow before purchasing a Label.