Use the Mailhub Postman Collection

Outcome

Import the generated collection and environment, configure your supplied API base URL and credentials, authenticate, then use the 12 public requests with current workflow identifiers. The collection is a convenience tool, not an SDK or a complete application.

What the collection contains

The collection contains exactly 12 public requests in five folders. It is generated deterministically from the approved public contract and has no unsupported endpoints.

Folder	Requests
Authentication	Create access token; Refresh access token; Revoke refresh token
Orders	Create order; Create an Order with Rates; List orders; Get order; Update order status
Rates	Get shipment rates
Labels	Buy label; Download label; Cancel label

V2 uses the required wrapped order body and creates one Order per request; it is not batch creation. The API Reference remains the complete schema source.

Postman and the API Playground

Two ways to send the same public operations, and neither replaces the other:

• The API Playground guide covers the browser tool, which runs the public operations against a configured Sandbox API and handles the token exchange for you.
• This collection runs them from your own API client, against whichever base URL you configure.

The two share no session, token, or variable state. Authenticating in one does not authenticate the other, and a Playground run writes nothing into your Postman environment.

Download the collection and environment

• Collection: /postman/MailHub-Public-API.postman_collection.json
• Environment template: /postman/MailHub-Public-API.environment.template.json

Import into Postman

1. Download and import both files.
2. Select the imported environment.
3. Populate only the user-supplied values below.

Configure variables

Collection test scripts write automatic values as collection variables. The imported environment is where you enter the initial configuration.

Variable	Who sets it	When used	Sensitive	Auto-populated	Reset guidance
baseUrl	You (USER_REQUIRED)	Every request	No	No	Replace when changing the configured environment.
apiKey	You (USER_REQUIRED)	Create access token	Yes	No	Clear before sharing an environment.
accessToken	Create/Refresh access token (AUTOMATIC)	Bearer requests	Yes	Yes	Re-authenticate or refresh; clear before sharing.
refreshToken	Create/Refresh access token (AUTOMATIC)	Refresh and revoke	Yes	Yes	Replace only from a successful token response; clear before sharing.
subAccountId	You (USER_OPTIONAL)	Requests with the optional header	No	No	Leave empty unless using an authorized Sub-account; replace when scope changes.
orderId	Create order or Create an Order with Rates (WORKFLOW_DERIVED)	Get/update Order	No	Yes	Replace after selecting another Order.
shipmentId	Create order or Create an Order with Rates (WORKFLOW_DERIVED)	Rates and Label purchase	No	Yes	Replace after selecting another Shipment.
rateId	Rate/create-and-rate response (WORKFLOW_DERIVED)	Buy label	No	Yes	Inspect returned rate.id values and replace with the chosen Rate.
labelId	Buy label (WORKFLOW_DERIVED)	Download and cancel	No	Yes	Clear before another Label workflow; Buy label clears it first.
labelFormat	You (USER_OPTIONAL)	Download label	No	No	1 (PDF) is the template default; 2 = ZPL 300 DPI, 3 = ZPL 203 DPI, 4 = ZPL 600 DPI.

Authenticate

Run Create access token with apiKey. On a successful response, its test script stores accessToken and refreshToken; Refresh access token replaces both on success. The collection does not refresh automatically. Revoke refresh token is separate and does not make a general repeat-safety promise.

Run the standard V1 Order flow

Start with List orders if you want a read-only first request. Create order captures orderId and the first Shipment's shipmentId; it does not rate during creation. Get order and Update order status can use an existing orderId. Then run Get shipment rates for a selected Shipment. These requests can also be used independently when you supply the relevant identifier; no Packed prerequisite is documented.

Run the create-and-rate flow

Create an Order with Rates sends one wrapped order and immediately returns Rate results by Shipment. Its script captures the Order and first Shipment identifiers and, when present, the first returned rate.id. A no-Rate 422 may occur after Order persistence; do not blindly repeat the request. Label purchase remains a separate V1 request.

Select a Rate and buy a Label

The generated Rate scripts may place the first returned rate.id in rateId as a convenience. Do not infer that the first response entry is cheapest, recommended, or otherwise preferred. Inspect the returned Rates and set rateId to the client-selected rate.id before Buy label.

Buy label uses rateId, clears stale labelId before handling its response, and captures only data.postageLabel.id. The root data.id is not a Label identifier. Download label and Cancel label both use {{labelId}}.

State-changing requests can be ambiguous

After a timeout or lost response, do not blindly repeat Label cancellation — the current public contract defines no idempotency or reconciliation for it. Label purchase is the exception: resending the same purchase request replays its outcome instead of buying a second Label, and a 202 means it is still running. See Buy a Label and Retries and Ambiguous Outcomes.

Download or cancel a Label

Download Label 200 is binary; inspect its actual status and Content-Type. The declared success media types are application/pdf and application/zpl (all three ZPL resolutions share one media type). A 202 is pending/still generating, not binary success; no polling interval, Retry-After, filename, cache, or eventual-success guarantee is public. Cancellation uses the same labelId and has the ambiguity boundary above.

Use Sub-account scope

subAccountId is optional. Its X-SubAccount-Id effect varies by operation, so review Work with Sub-accounts rather than treating it as authorization or applying it uniformly.

Reset or clear workflow variables

Before moving to another Order or Shipment, replace orderId, shipmentId, and rateId. Clear labelId before a new Label workflow; Buy label also clears it before a successful capture. Token values are automatic, but clear apiKey, accessToken, and refreshToken before exporting or sharing an environment.

Security guidance

Never commit, export, or share a populated environment containing keys or tokens. Use placeholders in examples, do not log Authorization headers, and keep separate environments for the configurations your application uses. Do not embed secrets in the collection source.

Troubleshooting

• Select the imported environment when a variable is unresolved.
• For authentication, validation, scope, and stale-identifier errors, use the relevant Error Handling page and verify the current variable.
• For an invalid create-and-rate body, confirm the required top-level order wrapper.
• For create-and-rate no-Rate 422, binary 200 versus pending 202, or ambiguous Label results, follow Production Readiness rather than inventing a retry or reconciliation flow.
• If the request count or generated files differ, download the current artifacts again; the collection should contain exactly 12 requests.

Collection limitations

The collection carries no execution surface of its own beyond Postman, and no tracking, webhook, or SDK workflow; no fixed public host; no batch Order creation; no automatic reconciliation; and no universal retry safety. Postman examples do not replace API Reference schemas. Browser-based Sandbox execution is a separate surface — see the API Playground guide.

Next steps

• API Reference
• API Playground guide
• Production Readiness
• Release Notes