Skip to main content

Sandbox

Sandbox is where you exercise the Mailhub public API before you point an integration at Production. It speaks the same documented contract as Production — the same operations, the same request and response shapes — so the client you build against Sandbox is the client you ship.

Sandbox and Production credentials​

Your Mailhub account has two API keys:

KeyPrefixUse it with
Sandbox API keymh_test_the Sandbox API
Production API keymh_live_the Production API

Both are viewed in the authenticated Mailhub application under Account → API Keys, and neither is managed through a public operation. See Prepare Your Mailhub Account.

The prefix tells you which key you are holding. That is all it does: it is a label on the credential, not a switch. It does not select an environment for you, and it does not decide how carriers are called. Whether a credential is accepted is answered by the API you send it to.

Exchange the key for an access token exactly as you would in Production — see Authentication and Token Lifecycle. The Sandbox API base URL is https://api-sandbox.mailhub.com. Configure it the same way you configure MAILHUB_API_BASE_URL for any environment — see API Conventions.

What you can test​

The Mailhub public API currently contains 12 operations, and Sandbox serves that same public contract. You can work through a complete integration path:

  • exchange an API key for a token, refresh it, and revoke it
  • create Orders, list them, read one, and update Order status
  • request Rates for a Shipment
  • buy a Label, download it, and cancel it

The API Reference is the complete schema source for all twelve. The guides carry the workflows — buy a Label, download a Label, and work with Sub-accounts.

API Playground​

The API Playground guide covers the browser tool that runs those same twelve operations against your configured Sandbox API, with authentication handled for you. It is a separate surface from the API Reference, which stays read-only. Open the API Playground when you are ready to send requests.

What Sandbox establishes​

Mailhub publishes these semantics for Sandbox.

  • Sandbox transactional activity is isolated from Production.
  • Sandbox operations do not affect Production transactional data.
  • Sandbox label and carrier activity is non-billable.
  • Sandbox activity does not consume Production wallet funds.
  • Sandbox data persists.

Three things Mailhub does not currently publish, so that you can plan around their absence rather than discover it.

  • Mailhub does not currently provide a customer-triggered Sandbox account reset.
  • Mailhub does not currently publish an automatic Sandbox data cleanup schedule.
  • Mailhub does not currently publish separate Sandbox-specific quotas or rate limits.

Because Sandbox data persists and nothing clears it for you, use identifiers and reference values in your test fixtures that you can still recognise weeks later.

What Sandbox does not guarantee​

Sandbox is a place to exercise the contract, not a preview of your Production results.

Treat the documented contract as the thing Sandbox and Production share, and treat everything that depends on your account, your carriers, or the deployment as something to re-check on the other side. The Go-Live Checklist is where that re-checking is written down.

Next steps​