Web Tools
April 2019
ExpressMail API Retirement Transition Guide
Table of Contents
1.1 Request
XML Considerations
1.2 Response
XML Considerations
1
ExpressMail API Retirement
We are
advising applications currently using the Web Tools ExpressMail API to transition over to the ExpressMailCommitment API at your earliest convenience to
receive accurate Priority Mail Express service standards and commitments. You
may use your current USERID and the following URL scheme, host and path to
access the ExpressMailCommitment API:
·
TEST: http://stg-production.shippingapis.com/ShippingApi.dll
·
PROD: http://production.shippingapis.com/ShippingApi.dll
The steps below
will outline the best way to transition. Please be sure to review the API documentation
at https://www.usps.com/business/web-tools-apis/welcome.htm
for more details on all of the features and functionality.
1.1 Request XML Considerations
The below table
includes the XML request tags that currently exist in the ExpressMailCommitment
API:
|
Tag Name |
Occurs |
Description |
Type |
|
ExpressMailCommitmentRequest |
required |
|
(group)
|
|
ExpressMailCommitmentRequest USERID |
required |
This
attribute specifies your Web Tools ID. See the Developer's Guide for
information on obtaining your USERID. For
Example: <ExpressMailCommitmentRequest
USERID="your USERID"> |
string |
|
ExpressMailCommitmentRequest / OriginZIP |
required
|
5
Digit ZIP Code of the package destination.
For
example:
<OriginZIP>90210</OriginZIP> |
string |
|
ExpressMailCommitmentRequest / DestinationZIP |
required |
Origination
and destination ZIP Codes must be valid and must be 5 digits. For example: <DestinationZIP>20770</DestinationZIP> |
string |
|
ExpressMailCommitmentRequest / Date |
required |
Date
package is shipped. Can be left
blank. Can use formats MM/DD/YYYY or
DD-MMM-YYYY. For example: <Date>05-May-2014</Date> |
string |
|
ExpressMailCommitmentRequest / DropOffTime |
optional |
Time
package is shipped. This tag can be
omitted or left blank. Use format
HH:MM such as 13:30. For example: <DropOffTime>15:00</DropOffTime> |
string |
|
ExpressMailCommitmentRequest / ReturnDates |
optional |
Indicates
if Scheduled Delivery and Effective Acceptance dates should be returned. Specify ‘true’ or ‘false’ For example: <ReturnDates>true</ReturnDates> |
string |
|
ExpressMailCommitmentRequest / PMGuarantee |
optional |
Indicator
to display Guarantee information for applicable service types. Valid Values: “Y”
= Yes, display “N”
= No, do not display (Default Value) |
String |
|
ExpressMailCommitmentRequest |
required
once |
|
(alias) |
The following table
demonstrates the XML request and the highlighted updates needed when
transitioning to ExpressMailCommitment:
Step 1) Replace the API Name in the URL and opening request tags:
·
API=ExpressMail&XML=<ExpressMailRequest
·
à API=ExpressMailCommitment&XML=<ExpressMailCommitmentRequest
Step 2) Replace the API Name in the closing request tags:
· </ExpessMailRequest> à
</ExpressMailCommitmentRequest>
|
http://production.shippingapis.com/ShippingApi.dll?API=ExpressMailCommitment&XML=<ExpressMailCommitmentRequest
USERID=" XXXXXXXX"> <OriginZIP>90210</OriginZIP> <DestinationZIP>26505</DestinationZIP> <Date></Date> </ExpressMailCommitmentRequest>
|
1.2 Response XML Considerations
The below table
includes the XML response tags that currently exist in the ExpressMailCommitment
API:
|
Tag Name |
Occurs |
Description |
Type |
|
ExpressMailCommitmentResponse |
required |
|
(group)
|
|
ExpressMailCommitmentResponse / OriginZip |
required
|
OriginationZip sent in request. |
string |
|
ExpressMailCommitmentResponse / OriginCity |
required
|
Originating
City. |
string |
|
ExpressMailCommitmentResponse / OriginState |
required
|
Originating
State. |
string |
|
ExpressMailCommitmentResponse / DestinationZip |
required |
DestinationZip sent in request. |
string |
|
ExpressMailCommitmentResponse / DestinationCity |
required
|
Destinating City. |
string |
|
ExpressMailCommitmentResponse / DestinationState |
required
|
Destinating State. |
string |
|
ExpressMailCommitmentResponse / Date |
required |
Date
package shipped. |
string |
|
ExpressMailCommitmentResponse / Time |
required |
Time. |
string |
|
ExpressMailCommitmentResponse / ExpeditedTransMessage |
optional |
Expedited
Transportation Message. Returned when applicable and the request has the ReturnDates set to true. |
string |
|
ExpressMailCommitmentResponse / MsgCode |
optional |
Message
Code. Returned when applicable and the request has the ReturnDates
set to true. |
string |
|
ExpressMailCommitmentResponse / Msg |
optional |
Message
Text. Returned when applicable and the request has the ReturnDates
set to true. |
string |
|
ExpressMailCommitmentResponse / EffectiveAcceptanceDate |
optional |
Effective
Acceptance Date. Returned when the request has the ReturnDates
set to true. |
string |
|
ExpressMailCommitmentResponse / Commitment |
optional |
Holds
the details of a commitment. Returned if valid. |
(group) |
|
ExpressMailCommitmentResponse / Commitment / Name |
optional |
Commitment
Name Valid
Values: ‘Blank’ 1-Day 2-Day 3-Day DPO Military |
string |
|
ExpressMailCommitmentResponse / Commitment / Time |
optional |
Commitment
Time. (eg: 3:00 PM) |
string |
|
ExpressMailCommitmentResponse / Commitment / Sequence |
optional |
Commitment
Sequence Valid
Values: Seq
# Service Standard A0110 1-Day at 10:30 AM B0110 1-Day at 10:30 AM HFPU A0112 1-Day at 12:00
PM A0115 1-Day at 3:00 PM B0115 1-Day at 3:00 PM HFPU A0210 2-Day at 10:30 AM A0212 2-Day at 12:00 PM A0215 2-Day at 3:00 PM B0210 2-Day at 10:30 AM HFPU B0215 2-Day at 3:00 PM HFPU |
string |
|
ExpressMailCommitmentResponse / Commitment / Location |
optional |
Groups
drop off location information. |
(group) |
|
ExpressMailCommitmentResponse / Commitment / Location /
ScheduledDeliveryDate |
optional |
Scheduled
Delivery Date. Returned when the request has the ReturnDates
set to true. |
string |
|
ExpressMailCommitmentResponse / Commitment / Location /
CutOff |
optional |
Cut-Off
Time. |
string |
|
ExpressMailCommitmentResponse / Commitment / Location /
Facility |
optional |
Facility
Type Valid
Values: “POST
OFFICE” “PRIORITY
MAIL EXPRESS COLLECTION BOX” “AIR
MAIL FACILITY” |
string |
|
ExpressMailCommitmentResponse / Commitment / Location /
Street |
optional |
Facility
Street |
string |
|
ExpressMailCommitmentResponse / Commitment / Location /
City |
optional |
Facility
City |
string |
|
ExpressMailCommitmentResponse / Commitment / Location /
State |
optional |
Facility
State |
string |
|
ExpressMailCommitmentResponse / Commitment / Location /
ZIp |
optional |
Facility
Zip Code |
string |
|
ExpressMailCommitmentResponse / Commitment / Location / IsGuaranteed |
optional |
Indicates
if Guarantee is offered. Will only be returned if the PMGuarantee
in the request is set to “Y”. Valid
Values: “1” = Guaranteed “2” = No Guarantee “3” = Temporary No Guarantee |
string |
|
ExpressMailCommitmentResponse / Message |
optional |
Message
indicating over 200 location, when there are more than the 200 returned. |
string |
The ExpressMailCommitment
API will return additional information as well as all the information
previously returned for the ExpressMail API. To
demonstrate see the response below for the above XML request:
|
ExpressMailCommitment Response |
|
<ExpressMailCommitmentResponse> <OriginZIP>90210</OriginZIP> <OriginCity>BEVERLY HILLS</OriginCity> <OriginState>CA</OriginState> <DestinationZIP>26505</DestinationZIP> <DestinationCity>MORGANTOWN</DestinationCity> <DestinationState>WV</DestinationState> <Date>16-Jan-2019</Date> <Time>8:58AM</Time> -<Commitment> <CommitmentName>1-Day</CommitmentName> <CommitmentTime>3:00 PM</CommitmentTime> <CommitmentSequence>A0115</CommitmentSequence> -<Location> <CutOff>4:00 PM</CutOff> <Facility>POST OFFICE</Facility> <Street>325 N MAPLE DR</Street> <City>BEVERLY HILLS</City> <State>CA</State> <Zip>90210</Zip> </Location> -<Location> <CutOff>3:00 PM</CutOff> <Facility>POST OFFICE</Facility> <Street>323 N CRESCENT DR</Street> <City>BEVERLY HILLS</City> <State>CA</State> <Zip>90210</Zip> </Location> +<Location> +<Location> +<Location> +<Location> +<Location> </Commitment> -<Commitment> <CommitmentName>1-Day</CommitmentName> <CommitmentTime>3:00 PM</CommitmentTime> <CommitmentSequence>B0115</CommitmentSequence> +<Location> +<Location> +<Location> +<Location> +<Location> +<Location> -<Location> <CutOff>4:30 PM</CutOff> <Facility>EXPRESS MAIL COLLECTION BOX</Facility> <Street>9665 WILSHIRE BLVD</Street> <City>BEVERLY HILLS</City> <State>CA</State> <Zip>90210</Zip> </Location> </Commitment> </ExpressMailCommitmentResponse> |