Prepare Your Mailhub Account

Prepare these items in the authenticated Mailhub application before using the public API. They are not managed through public integration endpoints.

API-key access

In the Mailhub application, open Account, then API Keys. The current UI shows fixed Sandbox API Key and Production API Key entries. Select View, confirm the account password, copy the key to secure server-side storage, and conceal it again when finished. The application also conceals a revealed key automatically.

The same UI can activate or deactivate an API key. Access to account and key-management controls depends on your role permissions; ask an account administrator when a required control is unavailable.

The Sandbox key begins mh_test_ and the Production key begins mh_live_. Use the Sandbox key while you are building against the Sandbox API — see Sandbox, and the API Playground guide to run the public operations from the browser.

Keep credentials out of clients and logs

Never put an API key, access token, or refresh token in a URL, browser bundle, source control, ticket, chat, screenshot, analytics event, or log. The portal never needs a real credential.

Do not assume support for public API-key creation, custom key names, scopes, expiry, automatic rotation, a public rotation endpoint, or a fixed API host.

Account and optional Sub-account context

Your authenticated Account is the default integration scope. If a workflow needs an authorized Sub-account, pass its optional X-SubAccount-Id header consistently on the operations where that scope applies. The Sub-account must belong to the authenticated Account.

Public documentation calls this entity a Sub-account. The current private application still uses Subcompanies in parts of its UI; that is a transitional UI label, not a public API route or a second public entity.

The header's exact effect is operation-specific: it filters Order listing and tags Order creation, and on the carrier operations — requesting Rates and buying a Label — the selected Sub-account can narrow the carriers available to it. It does not change pricing. The remaining operations either validate the header or take no effect from it. See Authentication and Token Lifecycle before choosing a scope.

Wallet and carrier readiness

Review wallet/funding readiness and carrier configuration in the authenticated Mailhub application when they apply to your account. Rates and Labels can depend on account context, environment, carrier configuration, wallet/funding, and shipment input. A configured or visible carrier does not guarantee that a request returns a rate.

This page does not promise a carrier service, negotiated rate, billing model, refund timing, cancellation outcome, or Production availability.

Ready for authentication?

Proceed when you can confirm all of the following:

• You have selected the Account that owns the integration.
• You can securely reveal an active API key in the Mailhub application.
• You know whether the workflow needs an authorized optional Sub-account.
• You have checked any account-specific wallet/funding and carrier readiness.
• You have the configured MAILHUB_API_BASE_URL value for your account.

Next, continue to Authentication and Token Lifecycle.