USPS API: Estimate postage
Estimates domestic USPS Post Office retail postage between two ZIP Codes for a letter, large envelope, package or flat-rate packaging, by weight and mailing date. Media Mail is left out; a zero-weight letter counts as one ounce. Prices are retail, cheapest first, with each service's estimated delivery.
Unofficial. Not affiliated with or endorsed by USPS.
Inputs
Values from the run on Oct 31, 2026, shown under Output.
- Width in optional
width_in Package width in inches, for example 6; defaults to a small box.
6 (default)
Number.
- Height in optional
height_in Package height in inches, for example 4; defaults to a small box.
4 (default)
Number.
- Length in optional
length_in Package length in inches, for example 8; defaults to a small box.
8 (default)
Number.
- Ship Date optional
ship_date Planned mailing date in YYYY-MM-DD, for example 2026-10-01; defaults to today (New York time).
Not set
- Weight (lb), required
weight_lb Weight in pounds, for example 2; enter 0 for a letter under a pound.
2
Number 0 or more.
- Weight Oz optional
weight_oz Additional ounces beyond the whole pounds, for example 8.
0 (default)
Number 0 or more.
- Origin Zip, required
origin_zip Five-digit ZIP Code where the item is mailed, for example 10001.
60601
Exactly 5 characters.
- Package Type optional
package_type Mailpiece or USPS flat-rate packaging type, for example package.
flat_rate_box
One of
letter,large_envelope,package,flat_rate_envelope,flat_rate_box. Defaultpackage.- Destination Zip, required
destination_zip Five-digit destination ZIP Code, for example 94105.
90001
Exactly 5 characters.
Input as JSON
{ "weight_lb": 2, "origin_zip": "60601", "package_type": "flat_rate_box", "destination_zip": "90001"}Output
{ "note": null, "services": [ { "currency": "USD", "page_link": "https://postcalc.usps.com/Calculator/ExtraServices?country=0&ccode=US&oz=60601&omil=False&dz=90001&dmil=False&retail=False&mdt=9/28/2026&mdz=8:00 AM&m=12&hscode=False&p=2&o=0&rect=True&l=0&h=0&w=0&g=0&mt=14&dok=XX&pt=r" , "retail_price": 13.65, "service_name": "Priority Mail Small Flat Rate Box", "included_extras": [ "USPS Tracking", "Insurance up to $100" ], "expected_delivery_date": "2026-10-01", "estimated_delivery_time": "Thu, Oct 1" }, { "currency": "USD", "page_link": "https://postcalc.usps.com/Calculator/ExtraServices?country=0&ccode=US&oz=60601&omil=False&dz=90001&dmil=False&retail=False&mdt=9/28/2026&mdz=8:00 AM&m=12&hscode=False&p=2&o=0&rect=True&l=0&h=0&w=0&g=0&mt=13&dok=XX&pt=r" , "retail_price": 24.8, "service_name": "Priority Mail Medium Flat Rate Box", "included_extras": [ "USPS Tracking", "Insurance up to $100" ], "expected_delivery_date": "2026-10-01", "estimated_delivery_time": "Thu, Oct 1" }, { "currency": "USD", "page_link": "https://postcalc.usps.com/Calculator/ExtraServices?country=0&ccode=US&oz=60601&omil=False&dz=90001&dmil=False&retail=False&mdt=9/28/2026&mdz=8:00 AM&m=12&hscode=False&p=2&o=0&rect=True&l=0&h=0&w=0&g=0&mt=12&dok=XX&pt=r" , "retail_price": 34, "service_name": "Priority Mail Large Flat Rate Box", "included_extras": [ "USPS Tracking", "Insurance up to $100" ], "expected_delivery_date": "2026-10-01", "estimated_delivery_time": "Thu, Oct 1" } ]}Code
curl https://api.fous.com/v1/runs \ -H "Authorization: Bearer $FOUS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"method":"usps.com/estimate_postage","input":{"weight_lb":2,"origin_zip":"60601","package_type":"flat_rate_box","destination_zip":"90001"}}' # Save as fous.py, then run: python3 fous.pyimport json, os, timefrom urllib.error import HTTPErrorfrom urllib.request import Request, urlopenAPI = "https://api.fous.com/v1/runs" KEY = os.environ["FOUS_API_KEY"]HEADERS = { "Authorization": f"Bearer {KEY}", "Content-Type": "application/json" ,}def call(url, body=None): data = json.dumps(body).encode() if body else None request = Request(url, data, HEADERS) try: with urlopen(request, timeout=120) as r: return r.status, json.load(r) except HTTPError as error: message = json.load(error)["error"]["message"] raise RuntimeError(message) from errorstatus, run = call(API, { "method": "usps.com/estimate_postage" , "input": { "weight_lb": 2, "origin_zip": "60601", "package_type": "flat_rate_box", "destination_zip": "90001" }})# 202: still going after 30 s. Ask again until it ends.while status == 202: time.sleep(2) status, run = call(f"{API}/{run['id']}")print(json.dumps(run["data"], indent=2))// Save as fous.mjs, then run: node fous.mjsconst api = "https://api.fous.com/v1/runs" ;const headers = { Authorization: `Bearer ${process.env.FOUS_API_KEY}`, "Content-Type": "application/json" ,};let response = await fetch(api, { method: "POST", headers, body: JSON.stringify({ "method": "usps.com/estimate_postage" , "input": { "weight_lb": 2, "origin_zip": "60601", "package_type": "flat_rate_box", "destination_zip": "90001" } }), signal: AbortSignal.timeout(120_000),});let run = await response.json();// 202: still going after 30 s. Ask again until it ends.while (response.status === 202) { await new Promise((done) => setTimeout(done, 2_000)); response = await fetch(`${api}/${run.id}`, { headers }); run = await response.json();}if (!response.ok) throw new Error(run.error.message);console.log(run.data);# Connect your agent to Fous once, over MCP (Streamable HTTP):# https://api.fous.com/mcp# Set FOUS_API_KEY first: create a key at https://app.fous.com/keys.# Claude Codeclaude mcp add \ --scope user \ --transport http fous https://api.fous.com/mcp \ --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"# Codexcodex mcp add fous \ --url https://api.fous.com/mcp \ --bearer-token-env-var FOUS_API_KEY# Cursor, VS Code, Windsurf, Cline and morenpx -y add-mcp https://api.fous.com/mcp -g -n fous \ --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"# Then ask your agent:# "Use Fous to run usps.com/estimate_postage# with {"weight_lb":2,"origin_zip":"60601","package_type":"flat_rate_box","destination_zip":"90001"}"Over HTTP, the answer’s data holds the output. A run still going after 30 seconds answers 202 with its id: ask GET /v1/runs/{id} until it ends.
Schema
Input schema
{ "type": "object", "required": [ "origin_zip", "destination_zip", "weight_lb" ], "properties": { "width_in": { "type": "number", "default": 6, "description": "Package width in inches, for example 6; defaults to a small box." }, "height_in": { "type": "number", "default": 4, "description": "Package height in inches, for example 4; defaults to a small box." }, "length_in": { "type": "number", "default": 8, "description": "Package length in inches, for example 8; defaults to a small box." }, "ship_date": { "type": "string", "description": "Planned mailing date in YYYY-MM-DD, for example 2026-10-01; defaults to today (New York time)." }, "weight_lb": { "type": "number", "minimum": 0, "description": "Weight in pounds, for example 2; enter 0 for a letter under a pound." }, "weight_oz": { "type": "number", "default": 0, "minimum": 0, "description": "Additional ounces beyond the whole pounds, for example 8." }, "origin_zip": { "type": "string", "maxLength": 5, "minLength": 5, "description": "Five-digit ZIP Code where the item is mailed, for example 10001." }, "package_type": { "enum": [ "letter", "large_envelope", "package", "flat_rate_envelope", "flat_rate_box" ], "type": "string", "default": "package", "description": "Mailpiece or USPS flat-rate packaging type, for example package." }, "destination_zip": { "type": "string", "maxLength": 5, "minLength": 5, "description": "Five-digit destination ZIP Code, for example 94105." } }}Output schema
{ "type": "object", "required": [ "services", "note" ], "properties": { "note": { "type": [ "string", "null" ] }, "services": { "type": "array", "items": { "type": "object", "required": [ "service_name", "retail_price", "currency", "estimated_delivery_time", "expected_delivery_date", "included_extras", "page_link" ], "properties": { "currency": { "type": "string" }, "page_link": { "type": "string" }, "retail_price": { "type": "number" }, "service_name": { "type": "string" }, "included_extras": { "type": "array", "items": { "type": "string" } }, "expected_delivery_date": { "type": [ "string", "null" ] }, "estimated_delivery_time": { "type": [ "string", "null" ] } } }, "description": "Available retail postage options, cheapest first." } }}- Price
- 1 credit per completed run (1¢ with pay as you go); failed runs are free.
- Method
usps.com/estimate_postage- Returns
- services (name, retail price in USD, estimated delivery time and date, included extras, USPS page link), note
Use it from your agent
Give your agent this line. It reads SKILL.md, gets a Fous API key and connects the Fous MCP server. Its run then takes the method usps.com/estimate_postage with the inputs above.
Ask your agent
- How much would it cost to mail a 3 lb 4 oz box measuring 12x10x6 inches from ZIP 60614 to 33139 next Tuesday? Show me the cheapest options and delivery dates.
- What's the USPS retail price to send a regular letter from 02139 to 98101, and how long will it take?
- I'm shipping a flat rate box from Austin 78704 to Denver 80202 on 2026-11-16 — what are my service options and prices on usps.com?
- Compare postage for a large envelope weighing 6 ounces going from 30309 to 10011, mailed on December 3rd.
- Check usps.com for the cheapest way to ship a 15 lb package (18x14x10) from 85004 to 04101 and when it would arrive.
See more
Tracks a UPS package by tracking number, with its status, delivery details and shipment history when available.
ups.com/track_packageLooks up the places, regions and coordinates for a postal code in a supported country on Zippopotam.us.
zippopotam.us/get_postal_codeFinds postal codes, place names and coordinates for a town and state or region in a country covered by Zippopotam.us.
zippopotam.us/search_postal_codesSearches a named Instacart store's guest-visible grocery products for a US ZIP code. Prices are in USD and can differ from in-store prices; stock estimates can change.
instacart.com/search_productsLooks up a medicine at Cost Plus Drugs by generic or brand name and returns the listed price and its breakdown for a strength, form and quantity, with the strengths and forms on offer. The drug price excludes shipping and taxes; standard shipping is shown separately.
costplusdrugs.com/get_drug_priceGets the US cash prices Drugs.com lists for a brand or generic medicine by strength, dosage form and quantity, optionally filtered. Where a range is listed the lower price is returned.
drugs.com/get_drug_pricesGets a home's details from Realtor.com by street address or Realtor.com property link: status, list price, value estimate, beds, baths, size, year built, HOA fee, property and tax history, nearby schools, flood risk and photos.
realtor.com/get_homeFinds OfferUp items for sale near a US city or ZIP code, with prices, condition, seller names, distance and links. Distances use approximate listing locations.
offerup.com/search_listings