Working with Labels

Take a Shipment from "no postage" to a printable Label, and undo a purchase without leaving the Order in a state Mailhub will not let you clean up. Each tool's exact input, output, and refusals live on its own page in the Tool Reference.

1. Get Rates

Ask mailhub_get_shipment_rates for the Shipment's Rates, and keep the id of the Rate you choose — that value is the rateId you buy with.

Rating needs update access to Orders even though nothing changes, and it needs no status preparation: you do not need to move the Order to Packed, or to any other status, before asking for Rates or buying a Label.

2. Buy the Label

mailhub_buy_label takes the shipmentId, the rateId you chose, and confirm: true.

This step spends real money

A confirmed purchase debits the account wallet. The wallet balance must cover it and the account's rolling 24-hour agent spend limit must have room — see Confirmations & Spend Safety for how those interact.

Buying is what moves the Order forward: LabelCreated is not a status you set. A purchase is allowed from Created, Processing, Picked, and Packed, and refused for a Cancelled, OnHold, Fulfilled, or Returned Order or one that already has an active Label — Order Statuses has the full model, and mailhub_buy_label lists each refusal.

For an Order on hold the purchase is refused before any wallet funds are held, and the refusal can name the status to resume the Order to. Resume it first, then buy.

3. Wait if the Label is still generating

A successful purchase can finish immediately or remain in progress for a short time. There is no dedicated purchase-status tool: use mailhub_get_order or mailhub_download_label again a few seconds later.

Repeating the same purchase is safe — the same Shipment and Rate will not buy a second Label. Starting a different purchase for the same Shipment while one is still running is refused as a conflict. That replay protection covers Label purchase only; it does not make the other changing tools safe to repeat.

4. Open the Label link

mailhub_download_label takes the orderId and shipmentId and returns a link, not a file.

The Label file never enters the conversation

Opening webUrl lands in the Mailhub application, where you sign in as usual and download or print the Label. An assistant cannot hand over the file itself, and no other download route is supported through MCP.

The result names which formats exist for that Label rather than returning any of them. If it is not downloadable, the reason matters more than the retry: MCP_LABEL_NOT_READY is worth asking again for, while a cancelled, failed, or never-purchased Label will not become downloadable by waiting — buy a replacement instead. mailhub_download_label carries the exact fields and every readiness code, and Errors & Troubleshooting carries their retry guidance.

5. Cancel a Label

mailhub_cancel_label takes the labelId and confirm: true.

• The carrier decides whether a void is possible. Cancellation is subject to the carrier's own rules for the Label in question.
• Repeating a cancellation is safe. An already-cancelled Label is not sent to the carrier a second time.
• The Order returns to Packed. That is what makes the Order cancellable again.

Cancelling a Label is not a refund

Cancelling does not automatically return funds to the wallet, and the original purchase still counts toward the account's rolling 24-hour agent spend limit for the rest of that window. Do not describe a cancellation to someone as money back.

Cancelling an Order that already has a Label

An Order with an active Label cannot be cancelled directly. Mailhub requires the carrier Label to be voided first, so the shipping state and the Order state cannot diverge — an Order marked cancelled while its Label is still live at the carrier is a package nobody expects.

1. Cancel the Label with mailhub_cancel_label.
2. The Order returns to Packed.
3. Cancel the Order from Packed with mailhub_update_order_status.

Next

Start at mailhub_get_shipment_rates.

• Something was refused? Errors & Troubleshooting.