Skip to main content

Production Readiness

Outcome​

Use this overview to separate what the current API documents from operational policies your application must own. It links to detailed guidance instead of defining a second API reference.

Contract versus client responsibility​

Mailhub public contract​

The API documents 12 public operations, their request and response schemas, declared status codes, and operation-specific X-SubAccount-Id behavior. The API Reference is complete.

Client-owned policy​

Your application owns retry budgets, timeouts, alerting, secure storage, internal request identifiers, and operator review after an ambiguous outcome.

Reliability boundaries​

  • Standard Order creation creates an Order without rating. Create an Order with Rates creates one Order per request with the required wrapped order body; it is not batch creation.
  • A create-and-rate no-Rate 422 may occur after the Order has been created. The public contract defines no idempotency or reconciliation operation for that case.
  • After a Label-purchase timeout or lost response, reissue only the same effective purchase request, or read the Order for the outcome; that operation replays rather than buying a second Label. A request that is not the same purchase is refused with 409, and two bounded conditions still apply: a Label cancelled before its result reached you is not replaced, and an unresolved carrier outcome refuses a new purchase until it settles.
  • Label cancellation has no equivalent replay contract. After a cancellation timeout or lost response, provider, local-state, and financial effects may be ambiguous; do not blindly repeat the cancellation.
  • A Label-download 200 is binary. A 202 means pending/still generating and carries a Retry-After header in seconds — wait for the value that response gives rather than an interval of your own. That header is scoped to this one response: the Label-purchase 202 does not carry it, no cross-operation polling interval is published, and no eventual-success promise is public.

Use the detailed guidance​

Keep Account/Sub-account selection explicit per operation using Work with Sub-accounts. The header is not authorization by itself and does not have universal behavior.