Skip to main content

How to start

Mailhub's public API supports exactly 12 public operations. Start by preparing your account in the Mailhub application, then exchange an API key for a token pair before making an authenticated request.

Current integration scope​

  • Token exchange, refresh, and revoke.
  • Create, list, get, and update an Order.
  • Create an Order with Rates — one Order per request with immediate Shipment rating.
  • Retrieve Shipment rates.
  • Purchase, download, and cancel a Label.

The public integration workflow is:

API key
  -> token pair
  -> Account / optional Sub-account scope
  -> Order
  -> Shipment
  -> Rates
  -> selected Rate
  -> Label
  -> binary Label asset

External applications use only the documented public API. Account selection, API-key management, wallet/funding, and carrier configuration are prepared in the authenticated Mailhub application; they are not public integration APIs.

Working through an AI assistant instead​

This section, and the rest of this portal, documents the API-key surface an application integrates against. If what you want instead is an AI assistant doing Mailhub work as your own signed-in user, that is a different surface with a different set of prerequisites — see Mailhub MCP.

What is not currently public​

The public API does not currently provide tracking, customer webhooks, official SDKs, standalone address verification, account/wallet/carrier management APIs, claims, insurance, manifests, pickups, or public batches.

The API Reference is a reading surface: it has no Try-It or in-page API Client, and it sends nothing. Running the public operations from a browser is a separate surface — the API Playground guide describes it, and the tool it documents sends only to a configured Sandbox API.

Before state-changing work​

Rates and Label availability can depend on account context, the supplied shipment, carrier configuration, and wallet/funding readiness. A carrier shown in the Mailhub application does not guarantee that every request returns a rate. Follow the account preparation checks before progressing beyond the safe first request.

The portal publishes no fixed API host. Configure MAILHUB_API_BASE_URL with the base URL supplied for your account, and run examples from your own client.

Next actions​

  1. Prepare Your Mailhub Account.
  2. Authentication and Token Lifecycle.
  3. Make Your First Request — a safe, read-only GET /api/v1/orders call.
  4. Choose how you want to work with the contract — none of these is required, and you can use more than one: the API Reference for request and response details, the API Playground guide to run the public operations against Sandbox from the browser, or the Postman collection in your own API client.
  5. Review the Order-to-Label Workflow before making a state-changing request, or take the executable path directly from Recipes.
  6. Use the First Label Guide for a safety-focused preparation checklist.
  7. Review Release Notes when assessing customer-visible changes.

Start from what you are building​

The same 12 operations serve several integration shapes. Pick the one closest to yours and follow its path; none of them needs a different request surface.

What you are buildingRead firstThen run
A first end-to-end shipping flowOrder-to-Label WorkflowRecipes
Rate shopping before you commitRatesCreate an Order and Get Rates in One Call
Shipping on behalf of your own customersAccount and Sub-account ScopeRun a Shipping Workflow for a Sub-account
Making an existing integration production-safeProduction ReadinessRecover a Label Purchase After 202
Undoing a Label you already boughtCancel a LabelCancel a Label

Core concepts​