Buy Label

mailhub_buy_label

Buy a shipping Label for a Shipment using a Rate returned by mailhub_get_shipment_rates. This is the one tool that spends money.

Permission and safety

Changes data	Yes
Confirmation	Required — confirm: true
Spends funds	Yes — real wallet funds
Permission	Update access to Orders

This spends real money

A confirmed call buys postage and debits the account wallet. The server refuses the call unless it carries confirm: true — but once that value is sent, the purchase is real. Agent spending is additionally capped per account over a rolling 24-hour window, and the cap is checked before any money moves and before the carrier is called.

Input

Field	Type	Required	Notes
shipmentId	string	Yes	The Shipment's UUID
rateId	string	Yes	The chosen Rate's UUID, from mailhub_get_shipment_rates
confirm	boolean	No	Defaults to false; the operation is refused unless the value is the boolean true

Example input

{
  "shipmentId": "22222222-2222-2222-2222-222222222222",
  "rateId": "33333333-3333-3333-3333-333333333333",
  "confirm": true
}

Output

Either the completed purchase, or an acknowledgement that the purchase was accepted and is still running.

• Completed — the Label is bought and its detail comes back.
• Still running — Mailhub accepted the purchase and is finishing it. There is no dedicated purchase-status tool; check the Order again with mailhub_get_order, or ask for the Label with mailhub_download_label a few seconds later.

Rules and common tool-specific errors

Mailhub validates the Rate against the Shipment, checks the Order's status, checks the agent spend limit and the wallet balance, and then buys the Label with the carrier. The Order moves to LabelCreated as a result of the purchase — you do not set that status yourself.

Order statuses that block a purchase

No status preparation is needed

You do not need to move the Order to Packed, or to any other status, before buying. Buying is what moves the Order on. Older material that described a Packed prerequisite is not correct.

A purchase is refused when the Order is:

Status	Why	What to do
Cancelled	The Order will not ship	Nothing — the Order is closed
OnHold	The Order is paused; the refusal names the status to resume it to	Resume it with mailhub_update_order_status, then buy
Fulfilled	The Order has already been handed over	Nothing
Returned	The Order came back	Nothing
LabelCreated	A Label already exists for it	Use mailhub_download_label, or cancel the existing Label first

A refusal for an on-hold Order happens before any wallet activity, so no funds are touched. Order Statuses sets out the whole fulfillment model these rules come from.

Retry rules for this tool only

• Repeating the same purchase does not buy a second Label. Asking again for the same Shipment and the same Rate returns the outcome Mailhub already recorded, and that record survives restarts on both sides.
• A different purchase for the same Shipment, while one is still in flight, is refused rather than queued. Let the first one settle.
• An unresolved carrier outcome is refused while Mailhub reconciles it. Wait and check the Order rather than buying again.
• This replay safety covers Label purchase. It does not extend to other tools — mailhub_create_order in particular will create a duplicate.

• A Rate is a point-in-time quote. A stale Rate is refused; rate again and buy the new one.
• A Label that was bought and then cancelled before its result came back is a terminal answer, not a retry. Buy a new Label if the Shipment still needs one.

Common tool-specific errors

Code	What it means	Retrying
MCP_CONFIRMATION_REQUIRED	The call did not carry confirm: true	Yes, confirming
MCP_INVALID_UUID	shipmentId or rateId is not a UUID	No — fix the value
MCP_WRITE_RATE_LIMITED	Too many changing calls for the account just now	Yes, shortly
Wallet.InsufficientFunds	The wallet balance is below the amount	After topping up in Mailhub
Wallet.McpSpendCapExceeded	The purchase would exceed the account's rolling 24-hour agent spend limit	After the window moves on, or after the limit is raised in Mailhub
LabelPurchase.InProgress	Another purchase for this Shipment is still running	After it settles
A carrier rejection or carrier unavailability	The carrier declined or could not be reached	Depends on the message — correct and retry, or retry shortly

Every code above, plus the access and shared failures this table does not cover, is listed in Errors & Troubleshooting.

Next

• mailhub_download_label — the printable Label afterwards.
• Working with Labels — the whole rate, buy, download, and cancel workflow.
• Confirmations & Spend Safety — the wallet and agent spend limit behind this purchase.