Skip to main content

USPS with Mailhub

Outcome​

You will learn how USPS fits into Mailhub's Rates and Labels workflow, how to recognize a USPS option in the Rates returned for your Shipment, and which boundaries apply when you build against it.

USPS adds no public endpoint. Everything on this page uses the same operations you already use for every other carrier.

How USPS fits into Mailhub​

USPS is one of the carrier options that can be returned when you request Rates:

prepare a Shipment
  -> request Rates
  -> Mailhub returns the eligible carrier/service options
  -> a returned Rate may identify USPS
  -> select one returned Rate
  -> buy the Label with the standard Label operation

An integration that already handles returned Rates needs no USPS-specific request path. See Rates and Labels for the carrier-generic models this page builds on.

Carrier availability depends on account configuration.

Why USPS has a section and other carriers do not​

USPS is the only carrier with dedicated public guide coverage on this portal today. That describes what is documented, not what the platform can do: the Rates and Label operations are carrier-agnostic, and a Rate response can carry carrier values other than USPS according to your Account, optional Sub-account, and environment configuration.

Read it the other way round and it would be wrong twice — this portal does not claim that Mailhub supports only USPS, and it does not guarantee that any other carrier is available to you. See Carrier Availability for what does decide availability.

Identify a returned USPS service​

Read carrier to recognize the option as USPS, and serviceName to recognize the service. A returned Rate is the only evidence that a service is usable for the Shipment you are rating.

{
  "id": "<returned Rate identifier>",
  "carrier": "USPS",
  "serviceName": "USPS Ground Advantage",
  "serviceCode": "<returned service code>"
}

The example shows recognition only. Read every value from the response; see the API Reference for the complete Rate schema.

Known service names​

Mailhub normalizes three known USPS service names:

Returned serviceNameGuide
USPS Ground AdvantageUSPS Ground Advantage
USPS Priority MailUSPS Priority Mail and Priority Mail Express
USPS Priority Mail ExpressUSPS Priority Mail and Priority Mail Express

Other USPS services may be returned with provider-supplied names. Match the known values above when you need those services, and treat an unrecognized returned serviceName as a returned service option — use its returned Rate id rather than inventing or translating a code.

Do not hard-code serviceCode. It is provider-dependent, and the public contract does not define a fixed list of values — see Rates.

Use USPS Rates and Labels​

The steps are the generic ones:

  1. Get Rates for the Shipment.
  2. Find a returned Rate whose carrier identifies USPS, and retain its id — see Select a Rate.
  3. Buy a Label with the nested rate.id request, and retain postageLabel.id from a successful response.
  4. Download a Label or Cancel a Label.

Get Rates and Label purchase behave the same way for a returned USPS Rate as for any other returned Rate.

To exercise that same sequence against a configured Sandbox from the browser, see the API Playground guide — it runs these public Rates and Label operations, and USPS needs no different request path there than it does here. USPS availability depends on account and environment configuration, so a returned Rate remains the only evidence that a service is usable for the Shipment you are rating.

For the input rules Mailhub applies before a Shipment can be rated, see Requirements & Restrictions. Carrier setup is completed in the authenticated Mailhub application, not through public integration endpoints — see Carrier Availability.

Current public boundaries​

The public API does not currently publish:

  • a USPS carrier-management, carrier-configuration, or credential setup operation;
  • a tracking status, tracking event, or webhook capability — trackingCode, where a Label result includes it, is an identifier only and is not a live feed;
  • a Cubic pricing contract;
  • any guarantee that the service is returned for a given Account or Shipment;
  • a fixed public catalog of serviceCode values.

Treat anything not documented in the API Reference as absent from the current public contract. Reuse the generic Production Readiness guidance for retries, ambiguous Label-purchase outcomes, diagnostics, and binary Label handling — none of it changes for USPS.

Next steps​