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.

Your application
  -> Mailhub public API  (12 documented operations)
  -> Order / Shipment / Rate / Label resources
  -> binary Label asset

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 polling contract. 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). The public contract defines no interval, no Retry-After, and no operation-status endpoint to poll, so the cadence is your application's decision. 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​