Skip to main content

Integration Architecture

A conceptual map of what your application talks to, what it gets back, and where the public boundary is drawn. Everything here is developer-facing: the Public Object Model has the resources, and the API Reference has the schemas.

What your application talks to​

One thing: the documented Mailhub public API, over HTTPS, with a bearer token your application obtained from an API key. There is no second endpoint family, no carrier-specific host, and no client library to install — every example in this portal is an HTTP request you issue yourself.

The boundary in full:

  • Your application talks to the Mailhub public API and to nothing else — 12 documented operations, reached over HTTPS with a bearer access token.
  • It gets back JSON responses carrying the public Order, Shipment, Rate, and Label resources and their identifiers, and — for a Label file — the binary asset as PDF or ZPL bytes, or a documented pending response.
  • There is no carrier-specific Mailhub endpoint or host. Mailhub manages the carrier connections; your application never connects to a carrier directly.
  • You obtain an API key and complete account and carrier setup in the authenticated Mailhub application, not through this API.
  • Choose Sandbox or Production. The same public contract applies to both, and keys and tokens do not cross environments.
  • Every access token acts for one Account. X-SubAccount-Id has operation-specific effects — see Account and Sub-account Scope.

The path through the objects​

The public workflow is a chain, and each link is a field you carry from one response into the next request:

API key
  -> access token + refresh token
  -> Account scope, optionally narrowed to a Sub-account per request
  -> Order
       -> Shipment(s)
            -> Rate results
                 -> the rate.id your application selects
                      -> Label  (postageLabel.id)
                           -> binary Label asset (PDF or ZPL bytes)
StepYou supplyYou keep
AuthenticateAPI keyaccess token, refresh token
Create an Orderaddresses, parcelsOrder id, Shipment ids
Get RatesShipment idthe id of the Rate you choose
Buy a LabelShipment id, rate.idpostageLabel.id
Download a LabelLabel idthe file bytes

Your application chooses the Rate. Nothing in the response ranks the options, and Mailhub does not select one for you.

Account and Sub-account scope​

Every request authenticates as an Account. An optional X-SubAccount-Id header selects a narrower scope on the operations whose contract gives it an effect — it tags a created Order, filters a list, or evaluates carrier availability. It is not a second credential and it does not decide which records you may act on; Account ownership does that either way. The per-operation matrix is authoritative.

Carriers are results, not endpoints​

The shipping API is carrier-agnostic. A carrier appears as a carrier and serviceName value on a returned Rate, and you act on it with exactly the same operations you use for every other Rate. There is no per-carrier endpoint family, no per-carrier request path, and nothing in a request that names a carrier — you select one by choosing a Rate that came back.

Where the portal publishes a carrier-specific guide, it explains how to recognise that carrier's services in a Rate response. It does not add an operation. See Carrier Availability for what decides which carriers a request can return.

What the public boundary excludes​

External applications communicate only with the documented public API. The following are not part of it, and nothing in a public response exposes them:

  • carrier account configuration, provider credentials, and carrier setup — all completed in the authenticated Mailhub application;
  • account, user, wallet, funding, and billing management;
  • any operation not listed in the API Reference.

The current flow is client-driven​

You retrieve state by calling documented operations. Mailhub does not call your application back:

  • No customer webhooks. Nothing is pushed to a URL you register; there is no registration operation.

  • No tracking feed. There is no tracking status or tracking-event capability in the public contract. Where a Label result carries a trackingCode, it is an identifier, not a stream of updates.

  • No operation-status endpoint. Two operations can answer before their work is finished — Label purchase can return 202, and a Label file download can return 202 while the asset is generated. In both cases you read the result later through a documented operation (Get Order and the download itself); there is no operation-status resource to poll. The two 202s differ in what they say about timing, and they are not one flow:

    • The Label-purchase 202 defines no interval and sends no retry header, so how often you read the Order back is your application's decision.
    • The Label-download 202 carries a Retry-After header in seconds. Wait for the value that response gives — it is a hint for that one response, not a schedule for the rest of the API, and not a promise that the file will be there next time.

    See Recover a Label Purchase After 202.

Design your integration around reading state when you need it, and record what you have already done rather than expecting a notification about it. See Retries and Ambiguous Outcomes.

How Mailhub uses webhooks​

Mailhub itself uses inbound webhooks internally with a small number of external providers it integrates with — for example, payment events from Stripe and lead events from Salesforce. In each case the provider calls Mailhub when something happens on their side; Mailhub validates the incoming event and processes the related internal workflow.

These integrations are managed by Mailhub, not by your application. They are separate from the public integration API described in this portal — there is no operation that lets your application register a URL, choose which events it receives, or otherwise take part in them.

Where to go next​