Create Order

mailhub_create_order

Create an Order from a sender address, a recipient address, and one or more parcels. It does not rate the Order and does not buy a Label, so it spends nothing.

Permission and safety

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

Confirmation is enforced by the server. A call without confirm: true is refused with MCP_CONFIRMATION_REQUIRED and creates nothing.

Creating twice creates two Orders

This tool is not idempotent. A second confirmed call with the same details creates a second Order — there is no deduplication behind it. If a call's outcome is unclear, look the Order up with mailhub_list_orders before confirming again.

Input

Field	Type	Required	Notes
order	object	Yes	The Order to create
confirm	boolean	No	Defaults to false; the operation is refused unless the value is the boolean true

order:

Field	Type	Required	Notes
toAddress	address	Yes	Destination (recipient) address
fromAddress	address	Yes	Origin (sender) address
shipments	array	Yes	One or more Shipments; each carries one parcel

Address — the same rules apply to both fromAddress and toAddress. Order creation through MCP is US domestic only:

Field	Type	Required	Rule
name	string	Conditional	Provide name, company, or both. Max 50 characters, printable ASCII
company	string	Conditional	Provide company, name, or both. Max 50 characters, printable ASCII
street1	string	Yes	Max 50 characters, printable ASCII
street2	string	No	Max 50 characters, printable ASCII
city	string	Yes	Max 50 characters, printable ASCII
state	string	Yes	Two-letter US state or territory code, for example TX
zip	string	Yes	Five digits, or ZIP+4 — 78701 or 78701-1234
country	string	Yes	US only. USA and United States are rejected
phone	string	Yes	A US number: ten digits with an area code starting 2–9, optionally prefixed with country code 1. +, spaces, dashes, dots and parentheses are accepted
email	string	No	Must be a valid address when supplied
residential	boolean	No

A phone number is required on both addresses

Sender and recipient each need a valid US phone number. This is not a carrier-by-carrier preference — an Order without both is rejected before any carrier sees it.

Shipment carries one parcel. Either name a package Mailhub recognises or give all three dimensions:

Field	Type	Required	Rule
weight	decimal	Yes	Greater than 0 and at most 70 pounds
predefinedPackage	string	Conditional	A package code Mailhub recognises. Omit it for a custom parcel; an unrecognised code is rejected and the message names it
length	decimal	Conditional	Required for a custom parcel — greater than 0
width	decimal	Conditional	Required for a custom parcel — greater than 0
height	decimal	Conditional	Required for a custom parcel — greater than 0

With a recognised predefinedPackage, the dimensions may be omitted; Mailhub uses the package's own. Without one, all three are required together — two of the three is rejected.

Example input

{
  "order": {
    "fromAddress": {
      "name": "Warehouse Team",
      "company": "Example Shipper",
      "street1": "500 Example Way",
      "city": "Columbus",
      "state": "OH",
      "zip": "43215",
      "country": "US",
      "phone": "5555550100"
    },
    "toAddress": {
      "name": "Sample Recipient",
      "street1": "72 Sample Street",
      "street2": "Apt 4",
      "city": "Austin",
      "state": "TX",
      "zip": "78701",
      "country": "US",
      "phone": "5125550142",
      "residential": true
    },
    "shipments": [
      {
        "parcel": {
          "weight": 2.5,
          "length": 12,
          "width": 9,
          "height": 4
        }
      }
    ]
  },
  "confirm": true
}

This is a complete, accepted request: copy it, change the values, and it still passes. It is not a minimal one. For each address, provide at least one of name or company — the sender here happens to carry both, and either alone would be accepted. street2 and residential are optional throughout. The parcel here is custom, which is why all three dimensions are present — swap them for a recognised predefinedPackage and they can go.

Output

Field	Contents
id	The new Order's identifier
createdAtUtc	When it was created, in UTC
createdAtDisplay	The same instant, formatted and labelled UTC
shipments	One entry per Shipment, each with its shipmentId

The new Order starts in Created. No Rates are returned and no Label is bought — those are separate, explicit steps.

Rules and common tool-specific errors

Before anything is sent, MCP checks that toAddress.street1 and fromAddress.street1 are present and that shipments holds at least one parcel. Mailhub then applies the full rules in the tables above — both addresses, and every parcel — and rejects the Order if any of them fails, naming the field. Nothing partial is created. Order creation through MCP is US domestic only; treat anything else as unsupported here.

• Repeating a confirmed call creates another Order. See the warning above.
• The identifiers in the response are what the next tools need: carry shipmentId into mailhub_get_shipment_rates.
• The Order is created for the account you signed in with. MCP has no sub-account scope today.

Common tool-specific errors

Code	What it means	Retrying
MCP_CONFIRMATION_REQUIRED	The call did not carry confirm: true	Yes, confirming
MCP_MISSING_FIELD	A required field is missing — the message names it	No — supply it
MCP_WRITE_RATE_LIMITED	Too many changing calls for the account just now	Yes, shortly
A validation refusal from Mailhub	An address or parcel value was not accepted	Yes, after correcting it

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

Next

• mailhub_get_shipment_rates — rate the Shipment this returns.
• mailhub_list_orders — check whether an Order already exists before creating another.
• Confirmations & Spend Safety — why repeating this call duplicates the Order.