Request a shipment

Requests one or more mail items to be shipped to the given address and recipient. Mail items in a single call may be split into multiple shipments; each shipment produces one entry in the response. If any item is in a state that cannot be shipped (already shipped, shredded, deposited, or past its storage deadline), the entire request is rejected with a 409 and no shipments are created. Shipping cost is determined asynchronously after labels are priced; the final cost arrives via the mailItem.forward.completed webhook and on GET /v1/mail-items/{id}. When consuming cost from the webhook, deduplicate via forwardDetails.id, which names the same shipment under an older name: mail items in the same shipment share the cost.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params

Body required in the request

mailItemIds
array of strings
required

IDs of the mail items to ship. Repeated IDs are treated as a single item.
If any item cannot be shipped (already shipped, shredded, or deposited),
the request is rejected with a 409 and no shipments are created.

CreateShipmentsRequestBody.mailItemIds*
string
required

Name on the shipping label. Person or company name.

string
required

Phone number the carrier can contact about the delivery. Include the
country code for numbers outside the US, such as +44 20 7946 0958; a
number without one is read as a US number.

address
object
required

Destination address for the supplied mail item IDs.

string
required

The shipping method for every shipment this call creates. It must appear
on each shipment's menu in the POST /v1/shipping-methods response for
the same mail items and destination. To use a different method for a
subset of the items, ship that subset in its own call.

Headers
string
required
Responses

Language
Credentials
Header
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json