USPS Web Tools guide

Besides its primary role – delivering mail, USPS allows several other functions by means of https://www.usps.com/webtools/. In order to use them you’ll need to make xml in conformance with USPS Web Tools documentation and send it as for example cURL request. Below given is a class that will handle all these cURL requests. It’s the class serving all the requests in this article. We’ll need to pass it only URL, API method name and the XML.


Here are the methods and samples that we can use:
1.US address verification (AddressValidateRequest)
First, form the XML with the test address and USERID that we get get by registering at https://www.usps.com/webtools/.

USPS address verification API method is called Verify and the URL for it is https://production.shippingapis.com/ShippingAPI.dll.
Let’s pass our XML, URL and method name into USPS::connectToUSPS() :

Let’s have a look at the resulting XML:

We see handful XML where we can obtain validated and normalized address from as well as see it’s valid. We can tweak connectToUSPS() method and parse resulting XML with SimpleXML:

Then we can read from returned value as follows:

Let’s make the address invalid and see how it looks:

As you dump the result you’ll see

As we see, the address is not validated. The error is in element. In practice it happens that there is warning in response asking for more detailed info. Often it needs to have suite, apartment etc if Address2 is building. You should populate apt, room, suite in the Address element then.

2. Generating return labels (MerchandiseReturnV4)
USPS Tracking Number – is a unique identifier of a parcel and return label is the label you can send to your customer for return shipment. Here is a sample of Merchandise Return label:

To get it create XML as below:

We recommend to refer to official USPS doc to understand each of the parameters here.
API USPS Web Tools that allows us to get return label is MerchandiseReturnV4, and the method call for this task will look like:

To get the image from the response we need to look into

Note that it is base64 encoded.

You can get a copy of label via email (RecipientEMail request parameter):

You can access the tracking number itself at

3. Getting shipment tracking status by its tracking number (TrackRequest)
You have to know only parcel’s tracking num in order to get actual status of its location. You should use https://trkcnfrm1.smi.usps.com/PTSInternetWeb/ service for that, but you can also do the same with Web Tools
Let’s form the XML:

And send it via TrackV2 API method which is available at https://production.shippingapis.com/ShippingAPI.dll, provided 30-digit tracking number of your shipment in TrackID parameter.

Look at the result:

We see that in TrackSummary there is the shipment current status, its date and also location. In TrackDetail elements there are some more details.

That’s it. This article is only a brief introduction into USPS Web Tools. You can find very detailed documentation and samples here

Author: Alexandr Cvirovsky

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.