API Playground

The API Playground sends real requests to your configured Sandbox API from the browser. You connect once per browser tab with a Sandbox API key, and it handles the token exchange and headers for every operation after that — including when you move between topics.

Open the API Playground to use it. This page is the guide to how it behaves; that route is the tool itself.

How it differs from API Reference

Two surfaces, two jobs:

	API Reference	API Playground
Purpose	Read the contract	Execute against Sandbox
Sends requests	No — read-only	Yes, to the configured Sandbox API
Credentials	Never asked for	Sandbox API key, for the session

The API Reference is a reading surface. It renders schemas, parameters, and responses, and it does not send anything anywhere. Execution lives only in the Playground.

Connect with a Sandbox API key

Paste a Sandbox API key — the one beginning mh_test_ — and connect. The Playground exchanges it for an access token and uses that token for every protected operation you run afterwards.

If you paste a key beginning mh_live_, the Playground stops you before anything is sent and tells you to use a Sandbox key instead. That check is client-side feedback so an obvious mistake costs you nothing; it is not a security boundary. The Sandbox API remains the authority on whether a credential is valid, and a well-formed mh_test_ key can still be rejected there.

Once connected, the key is shown masked — its prefix and last four characters — so you can tell which key is in use without the full value being present on the page.

Managed authentication

You do not send Authorization yourself. The Playground performs the token exchange when you connect and attaches the resulting bearer token to each protected request.

If an operation fails authentication, recovery is deliberately bounded:

1. One refresh. The Playground refreshes the token once and retries.
2. One re-authentication. If refresh does not resolve it, it exchanges your API key for a new token — but only when your key is available to it, which means only when you chose to have it remembered.
3. One replay. The original request is replayed once against the new session.

If that sequence does not succeed, the Playground stops and returns you to the connection form rather than looping. Nothing retries indefinitely, and a request is never replayed more than once.

Recovery is bounded on purpose

The same discipline applies to your own client. Attempt one refresh, replace the stored token pair only after a successful response, then retry the original request once — see Token Recovery.

Sub-account context

Type a Sub-account ID into the connection panel, or change it later under Edit context. It is a free-text field rather than a picker, because the public API publishes no Sub-account listing operation. Leave it empty to work as the main account.

Once a Sub-account ID is set, the Playground sends X-SubAccount-Id on every protected operation, not only on the ones the header changes something for. That is deliberate: the context belongs to your session rather than to one request, and MailHub sets the header on the way out whatever the request itself carried. The three Auth operations are the exception — they are passed through untouched, so you can experiment with them by hand without your session leaking into the experiment. Whether the header then has an effect is a property of the operation:

• On Rates and Label purchase, the selected Sub-account can narrow the carriers on offer to those enabled for it.
• It does not change pricing or markup on any operation.
• On token exchange, a supplied Sub-account may be validated, but it is not persisted and does not scope the session that follows.

The complete per-operation matrix is in Work with Sub-accounts — this page does not repeat it.

Supported operations

The Playground executes the 12 operations in the current Mailhub public API contract — the same set the API Reference documents, grouped by the same topics. It is built from that contract rather than from a list kept alongside it, so the two cannot drift apart.

Label purchase recovery

Buying a Label in the Playground follows the public purchase contract:

• 200 — the purchase completed, and the response carries the result.
• 202 — the purchase is still running. There is no operation-status endpoint to poll.

After a 202, or if a response never reaches you, you have two ways forward: read the Order for the outcome, or reissue only the same effective purchase request. Sending the same request again replays the original operation rather than starting a new one. A request that is not the same purchase is refused with 409 instead of competing with the one in flight.

Cancellation is not covered by that contract

Label cancellation has no equivalent replay guarantee. If a cancellation response is lost, treat the outcome as ambiguous and read the Order rather than sending the cancellation again.

The full treatment is in Buy a Label and Retries and Ambiguous Outcomes.

Label downloads

A Label download returns binary content. The Playground offers it as a file download and uses the filename the server supplies when one is available, falling back to a generated name when it is not.

Which formats a Label is available in follows the public LabelFormat contract in the API Reference — see Download a Label for the workflow and Binary Labels for handling the bytes in your own client.

Session and storage behavior

The Playground keeps as little as it can:

• Your API key is held in memory for the session. It is stored on your device only if you explicitly choose to have it remembered.
• Access and refresh tokens are never stored. They exist only in the open page.
• Moving between topics keeps the session. Orders, Shipments and Labels are separate pages, and walking between them sends no authentication request.
• Reloading ends the managed token session. Tokens live in the open page and nothing else, so a reload has none to restore. You reconnect — instantly if your key is remembered, by pasting it again if it is not.

Automatic re-authentication is only possible when a remembered key exists, which is why step 2 of the recovery sequence above depends on that choice.

Use a Sandbox key here, and only here

Never paste a Production API key into a browser tool, including this one. Keep keys, access tokens, and refresh tokens server-side in your own integration — see Security.

When the Playground is unavailable

The Playground exists only where a Sandbox API has been configured for the portal. If none is configured, the Playground is unavailable and says so.

It never falls back to another environment. There is no configuration in which the Playground sends a request to Production.

The API Reference is unaffected either way — it is read-only and stays available.

Next steps

• Recipes — the same operations as copyable requests for your own client.
• Move to Production — the credential and base-URL switch, and what not to carry across with it.
• Go-Live Checklist — what to verify before launch.
• Sandbox — the section this tool belongs to.