Using a different carrier? See Package Tracking.

Introduction

Zembula connects to USPS through an app that you create in the USPS Business Portal. Zembula uses the app only to look up tracking numbers with USPS's Tracking API. It never creates labels or changes anything in your USPS account.

This guide covers creating the app, copying its credentials, and connecting them in the Zembula platform. You enter the credentials in Zembula yourself.

Who can do this

You need a USPS Business Account. You sign in to the USPS Business Portal with it, or create one there.

USPS only shares a package's tracking with a company whose Mailer ID (MID) is in the package's barcode, or who is authorized for that MID. If you print your own labels under your own MID, your app can track those packages at no cost. If another company prints your labels under a MID you aren't authorized for, USPS refuses those lookups and the image shows no tracking.

In that case, ask the company that prints your labels about USPS tracking access, or ask your Zembula team about using your order data for Package Tracking instead.

In Zembula, only account Admins can connect USPS. Other users can open the Package Tracking page, but they can't change it.

Before you go live

Each time an image with USPS tracking loads, Zembula can ask USPS for the latest scans. So each email open can use one USPS tracking call.

USPS limits how many calls each app can make per hour. When your app goes over its quota, USPS refuses calls and the image can't show tracking for those loads.

Before you go live, ask USPS for a quota that covers the opens you expect: submit a USPS API service request on the USPS Email Us page.

Create the app

Sign in to the USPS Business Portal with your USPS Business Account, or create an account there.
Select My Apps at the top of the page, then Developer Apps.
Click Add App and create the app. Tracking is part of USPS's default API product, so you don't need to request it.
Review and accept USPS's updated API Terms & Conditions under My Apps → Developer Apps → Manage. USPS asks shippers to accept them to keep their tracking access.

Copy the credentials

Select your app and copy the Consumer Key and the Consumer Secret from its Credentials section.

Keep the Consumer Secret private. Don't send it by email or chat. You enter it yourself in the Zembula platform in the next step.

Connect USPS in Zembula

In the Zembula platform, open Data Sync → Integrations and select the Data integrations tab.
Click Set up on the Package Tracking tile. If Package Tracking is already set up, the button reads Open instead.
If Package Tracking is off, click Turn on. The page shows Setting up the builder source… and then Use INTERFACES › Package Tracking in the builder.
Under Carriers, click Add on the USPS row.
The USPS row lists Consumer Key and Consumer Secret. Click Paste a key next to Consumer Key. The Paste your USPS keys dialog opens.
The dialog has two fields, Consumer Key and Consumer Secret. Paste each value into the field with its name.
Click Connect.

The button reads Verifying… while Zembula saves your credentials. The USPS row then reads Connected — starts answering within the hour.

Zembula doesn't test your credentials with USPS when you connect. A wrong key, or a package whose MID USPS won't share with you, shows up later as missing tracking. Check it with Try it below.

If order data is live for Package Tracking, the USPS row reads Connected — waiting: carriers and order data can't run together until the next release. To switch, click Use USPS instead. This turns order data off and USPS on. Content that sends only an order ID then shows your fallback.

Try it

Add INTERFACES › Package Tracking to a draft image in the builder, turn on Simulate, and preview it with the tracking number of a label you printed under your own MID. If a number you know is real shows no tracking, check the credentials and the Mailer ID rule above.

The Status section at the bottom of the Package Tracking page also lists anything that needs attention.

Using USPS in your content

Send each shipment's tracking number in tracking_number and its carrier in carrier. Zembula doesn't work out the carrier from the tracking number, so always send the carrier.

A carrier value goes to USPS when it contains USPS as a word, or Postal Service, Stamps.com, Endicia or US Mail, in any case. For example: USPS, usps, USPS_PRIORITY_MAIL, United States Postal Service, US_POSTAL_SERVICE or Stamps.com.

Send the tracking number as text, not as a number. USPS tracking numbers are often 20 to 22 digits, too long to send as a number. Zembula removes spaces and hyphens for you.

What shoppers see

Status: the stage of the latest scan USPS reports when the image loads, such as Label Created, In Transit, Out for Delivery or Delivered. A USPS scan Zembula can't classify reads In Transit.
Estimated delivery: USPS's expected delivery date, labelled Expected Delivery. Without one, USPS's predicted date. For Priority Mail Express with neither, the guaranteed date, labelled Guaranteed Delivery. After delivery it reads Delivered, with the delivery time.
Returns: once a package starts back to the sender, later scans read Returning to Sender, and Returned to Sender when it arrives.
Tracking link: the package's page on usps.com.
Manage delivery link: none. Tracking.manage_delivery_url stays empty for USPS.
Action link: after a missed delivery, or when a signature is needed, Tracking.Activities.Current.ActionRequired.action_url links to USPS's redelivery page. When the package waits for pickup, it links to a map of the pickup location, or to USPS's location finder for that ZIP Code.

Where your credentials are kept

The Consumer Key and Consumer Secret are saved as encrypted secrets. They can't be read back: the platform only shows their last four characters. They're listed under Data Sync → Secrets & Configs, and they can only be sent to USPS's API (apis.usps.com).

To change your credentials, open the Package Tracking page and click Replace key next to Consumer Key or Consumer Secret on the USPS row. To stop using USPS, click Disconnect.

More detail: Shared Secrets and Configs.