USPS Guide

The U.S. Postal Service (USPS) is the only delivery service that reaches every address in the nation: nearly 167 million residences, businesses, and Post Office Boxes. The Postal Service generally receives no tax dollars for operating expenses and relies on the sale of postage, products, and services to fund its operations.

This guide provides detailed information on utilizing USPS shipping with the EasyPost API, focusing on account setup, rates, label creation, pickups, tracking, and more.


Account Registration

Sign up for an EasyPost account to obtain a Test and Production API key. See Authentication and Key Management for more information.

Negotiated Service Agreement (NSA) rates are only available in Production mode.

Carrier Setup

Upon sign-up with EasyPost, users gain immediate access to Default Carrier Accounts, which can be enabled directly from the Dashboard. For additional carriers, EasyPost supports a Bring Your Own Account (BYOA) option for additional carriers. This requires users to register directly with the respective carrier.

Create an EasyPost USPS Carrier Account

  1. Log in to EasyPost and navigate to Account Settings.

  2. Select the Carriers tab.

  3. Select the EasyPost Carrier Accounts tab.

  4. Navigate to USPS Account in the list of carriers and select Create Account to complete the account creation process.

    USPS Create Account

Bring Your Own Credentials (BYOA) to EasyPost

  1. Register for a USPS account.
  2. Input carrier-specific credentials within the Carrier Account Dashboard for comprehensive rate access. For more information, see Bring Your Own Account to EasyPost.

USPS Account via API

The API structure specified by EasyPost can also be used to add a USPS carrier account.

curl -X POST \
  -H 'Content-Type: application/json' \
  -d '{
  "type": "UspsAccount",
  "description": "UspsAccount",
  "carrier_account": {
    "credentials": {
      "address_city": "VALUE",
      "address_state": "VALUE",
      "address_street": "VALUE",
      "address_zip": "VALUE",
      "company_name": "VALUE",
      "email": "VALUE",
      "phone": "VALUE",
      "shipper_id": "VALUE"

Software Requirements

Download an EasyPost Client Library or utilize the REST API with cURL.

Documentation Review

Examine the EasyPost Objects section to understand the API's structure, which is critical for constructing requests and interpreting responses.


Three USPS pricing tiers impact shipping rates:

  • USPS Retail Pricing: The rate paid at a local Post Office or other retail location.
  • USPS Commercial Pricing: Offers savings over USPS Retail pricing available to business shippers.
  • USPS Merchant Discount Pricing: A special negotiated rate between EasyPost and USPS that allows EasyPost to provide discounts below USPS Commercial Pricing.

See the USPS Rate Chart for more details.

Cubic Pricing is based on package volume and is useful for small, dense packages.

Service Levels

USPS has several service levels supported by EasyPost, each with specific transit times and conditions.

Transit Time
Max Dimensions (inches)
Max Weight (ounces)
First1-5 business daysCards, Letters and Flats only (no Parcels)See Predefined Packages (Card, Letter, Flat) for details13
Priority1-3 business daysCombined Length and Girth < 108in1120
Express1-2 daysCombined Length and Girth < 108in1120
GroundAdvantage2-5 daysCombined Length and Girth < 130in70
LibraryMail2-8 business daysCombined Length and Girth < 108in1120
MediaMail2-8 business daysCombined Length and Girth < 108in1120
FirstClassMailInternationalMust be rectangular, otherwise an additional charge may apply.15.994
FirstClassPackageInternationalService7-21 daysPackages (Other Than Rolls): Combined Length and Girth < 108inRolls (Tubes): Length: min 4in; max 36 in. Length plus twice the diameter (combined): min 6.75 in; max 42in.Some countries have specific prohibitions and restrictions64
PriorityMailInternational6-10 business daysCombined Length and Girth < 108in1120
ExpressMailInternational3-5 business daysCombined Length and Girth < 108in1120

Predefined Packages

USPS has several predefined packages supported by EasyPost. Predefined packages are an easy way to classify and price a package.

When using the EasyPost API, users should select a predefined package that matches the shipment's criteria and, if necessary, add weight to the request to obtain rates. The predefined package documentation provides detailed sample requests.

Predefined Package
Dimensions (inches)
Weight (ounces)
6in x 4.5in x 0.016in
11.5in x 6.125in x 0.25in
11.5in x 6.125in x 0.75in
12.5in x 9.5in
15in x 9.5in
12.5in x 9.5in
10in x 5in
12.5in x 9.5in
12.5in x 9.5in
10in x 6in
Varies based on service level
Varies based on service level
8.6875in x 5.4375in x 1.75in
11.25in x 8.75in x 6in
14.125in x 12in x 3.5in
12.25in x 12in x 6in
12.25in x 12.25in x 6in

Generating Shipping Labels

With EasyPost, the process for generating shipping labels for USPS is the same as generating them for any other carrier.

Review the Getting Started Guide for help generating a shipping label.

Label formats

EasyPost supports both domestic and international USPS labels in the following formats:

  • PNG
  • PDF
  • ZPL (may not be supported for letter and card label sizes)
  • EPL2

Use the EasyPost Label API for file-type requests or conversions.

USPS International Label USPS Domestic Label

See the Customs Guide for more information.

Label Size Options

Possible values for USPS shipping label sizes:

  • 4x6 (default)
  • 4x4
  • 8.5x11
  • 7x3 (Available when using predefined_package: Letter when First rate is purchased. See Predefined Packages)
  • 6x4 (Available when using predefined_package: Card or Letter and when First rate is purchased. See Predefined Packages)

Custom Text Label Options

Shipments can have a variety of additional options that can be specified when creating a shipment. These options include custom messages that can be printed on labels.

The locations of custom text fields will be displayed according to specific carrier label templates.

USPS Domestic Label

JSON Example

  "options": {
    "print_custom_1": "printCustom1",
    "print_custom_2": "printCustom2",
    "print_custom_3": "printCustom3",
    "invoice_number": "INVOICE12345",
    "label_size": "4x6",
    "label_format": "PNG"

Hazardous Materials (HAZMAT)

According to USPS, HazMat is any article or substance designated by the U.S. Department of Transportation as being capable of posing an unreasonable risk to health, safety, or property during transportation. In international commerce, HazMat is known as "dangerous goods." EasyPost is in full compliance with all USPS HazMat guidelines. Users are responsible for specifying the type of HazMat included in each shipment.

Shipping Restrictions

  • Extra services are restricted to only adult signatures or USPS Insurance.
  • Refunds for Priority Mail Express are not available for HazMat if delivered or attempted within three days of mailing.

Labeling Requirements

  • Service indicator H for identification.
  • HAZMAT - Surface Transportation Only below the return address for surface-only packages.
  • HAZMAT after USPS TRACKING # above the tracking barcode. USPS HazMat Label


Some HazMat types are restricted from aircraft and will only return available ground rates.

Shippers' Responsibilities

Shippers are responsible for other required HAZMAT markings and packaging documentation.

EasyPost Integration

EasyPost will upload HazMat-type electronic data to USPS.

Carrier Limitations

Due to the complexity of HazMat regulations and how each carrier handles them differently, many HazMat types are limited to specific carriers.

USPS Supported HazMat Types

See the table below for valid string values and descriptions of each HazMat type supported by USPS. For more information, refer to USPS Pub 52 Hazardous Material and Dangerous Goods Regulations.

AIR_ELIGIBLE_ETHANOLAir Eligible Ethanol Package
CLASS_1Class 1 - Toy Propellant/Safety Fuse Package
CLASS_3Class 3 - Package
CLASS_7Class 7 - Radioactive Materials Package
CLASS_8_CORROSIVEClass 8 - Corrosive Materials Package
CLASS_8_WET_BATTERYClass 8 - Nonspillable Wet Battery Package
CLASS_9_NEW_LITHIUM_INDIVIDUALClass 9 - Lithium Battery Marked - Ground Only Package
CLASS_9_USED_LITHIUMClass 9 - Lithium Battery - Returns Package
CLASS_9_NEW_LITHIUM_DEVICEClass 9 - Lithium batteries, marked package
CLASS_9_DRY_ICEClass 9 - Dry Ice Package
CLASS_9_UNMARKED_LITHIUMClass 9 - Lithium batteries, unmarked package
CLASS_9_MAGNETIZEDClass 9 - Magnetized Materials Package
DIVISION_4_1Division 4.1 - Mailable flammable solids and Safety Matches Package
DIVISION_5_1Division 5.1 - Oxidizers Package
DIVISION_5_2Organic Peroxides Package
DIVISION_6_1Division 6.1 - Toxic Materials Package (with an LD50 of 50 mg/kg or less)
DIVISION_6_2Division 6.2
EXCEPTED_QUANTITY_PROVISIONExcepted Quantity Provision Package
ID8000ID8000 Consumer Commodity Package
LIGHTERSLighters Package
LIMITED_QUANTITYLimited Quantity Ground Package
SMALL_QUANTITY_PROVISIONSmall Quantity Provision Package

USPS Resources


USPS will pickup the following package types for free:

  • Priority Mail Express
  • Priority Mail
  • Ground Advantage
  • USPS Returns
  • International


Request by 2:00 AM CST for same-day pickup. Packages must be properly sealed and ready for shipment.


EasyPost simplifies package tracking by offering two methods:

  • Tracking with an existing number and carrier.
  • Using a Tracker included with an EasyPost-purchased shipping label.

The service integrates webhooks for timely shipment updates. For detailed information on tracking methods, visit the Tracking Guide.

Additional Resources

Carrier Metadata

The Carrier Metadata endpoint can programmatically return information about USPS service levels, predefined packages, supported features, and shipment options.

Use this information to quickly integrate with USPS and make educated decisions about the mix of carriers for shipping needs. Additionally, the Carrier Metadata endpoint is available to retrieve comprehensive information about all carriers on the EasyPost platform, enhancing decision-making for carrier services.

Support and Troubleshooting

In addition to the guidance provided in our Carrier Guides, EasyPost offers support to assist with FAQs, troubleshooting issues, and inquiries related to the EasyPost platform.

Please visit the Help Center for more information.

USPS Web Tools

USPS offers public APIs called USPS Web Tools.

Talk to a Shipping Expert

For questions about getting started with USPS through the EasyPost API please talk to a Shipping Expert or contact our Support team.