International Shipping Labels

International 

Shipping Labels 

USPS Web Tools 

Application Programming Interface 

Reference 

Document Version 4.1 (01/22/2012)

To Our Customers 

In registering for use of the USPS Web Tools (Web Tools), you received a user ID that will allow you to begin sending calls to the server 

when you are ready. Any additional information or contact with you will occur as indicated on the registration form, please return to the Web 

Tools eCommerce API Technical Guides site for the most recent documentation from any of the Web Tools. 

If you require technical support, contact the USPS Internet Customer Care Center (ICCC). This office is manned from 7:00 AM to 11:00 PM 

EST daily. 

E-mail address: uspstechsupport@esecurecare.net 

Telephone: 1-800-344-7779 (7:00 AM to 11:00 PM EST daily) 

USPS Customer Commitment 

The United States Postal Service fully understands the importance of providing information and service anytime day or night to your Internet 

and e-commerce customers. For that reason, the USPS is committed to providing 24 x 7 service from our Web Tools servers, 365 days a 

year. 

Trademarks 

Express Mail, First-Class Mail, Global Express Mail, GXG, Global Priority Mail, Parcel Post, Parcel Select, Priority Mail, Express Mail International, First 

Class Mail International, Priority Mail International, USPS, and ZIP + 4 are registered trademarks of the U.S. Postal Service. 

Delivery Confirmation, Global Express Guaranteed, International Parcel Post, Priority Mail Global Guaranteed, Signature Confirmation, USPS Web Tools, 

and ZIP Code are trademarks of the U.S. Postal Service. 

Microsoft and Visual Basic are registered trademarks of Microsoft Corporation. 

Adobe Acrobat is a trademark of Adobe Systems Incorporated. 

DUNS is a registered trademark of Dun & Bradstreet. 

�Copyright 2012 United States Postal Service 

USPS Web Tools Reference: International Shipping Labels Web Tools (Document Version 4.1) ii

Table of Contents 

1 Introduction.......................................................................................... 5 

2 Express Mail International API ........................................................... 5 

2.1 Express Mail International Request .............................................................5 

2.1.1 API Signature.......................................................................................................5 

2.1.2 Request Diagram.................................................................................................6 

2.1.3 Request Parameters..........................................................................................13 

2.1.4 Request Example...............................................................................................25 

2.2 Express Mail International Response ........................................................29 

2.2.1 Response Diagram ............................................................................................29 

2.2.2 Response Parameters.......................................................................................31 

2.2.3 Tagged Label Diagram ......................................................................................33 

2.2.4 Response Example............................................................................................34 

3 Priority Mail International API .......................................................... 35 

3.1 Priority Mail International Request.............................................................35 

3.1.1 API Signature.....................................................................................................35 

3.1.2 Request Diagram...............................................................................................36 



3.2 Priority Mail International Response..........................................................62 





4 First Class Mail International API..................................................... 68 

USPS Web Tools Reference: International Shipping Labels Web Tools (Document Version 4.1) iii

4.1 First Class Mail International Request.......................................................68 

4.1.1 API Signature.....................................................................................................68 

4.1.2 Request Diagram...............................................................................................69 



4.2 First Class Mail International Response....................................................88 





USPS Web Tools Reference: International Shipping Labels Web Tools (Document Version 4.1) iv

1 

Introduction 

This document contains a Reference Guide to the International Shipping Labels APIs. See the Developer’s Guide to Web Tools APIs to learn the 

administrative process for gaining access to the Web Tools APIs as well as the basic mechanism for calling the APIs and processing the results. The 

Developer’s Guide also contains information on testing and trouble-shooting. 

For label specifications such as package dimensions, delivery information, etc., please refer to the International Mail Manual (IMM) at http://pe.usps.com/. 

2 Express Mail International API 

2.1 Express Mail International Request 

The table below presents the XML input tags for generating Live requests and the restrictions on the values allowed. An error message will be returned if an 

incorrect value is entered. Also, be aware of the maximum character amounts allowed for some tags. If the user enters more than those amounts, an error 

will not be generated. The Web Tool will simply pass in the characters up to the maximum amount allowed and disregard the rest. This is important 

since the resulting value could prevent a correct response. 

When building the XML request, pay particular attention to the order and case for tags. An error message will be returned if an incorrect value is entered. 

Remember that all data and attribute values in this document are for illustration purposes and are to be replaced by your actual values. For instance, a line 

of sample code may be: 

12345 

In this instance, you will replace “12345” with the destination ZIP Code for the domestic-bound package. 

2.1.1 API Signature 

Scheme Host Path API XML 

https:// secure.shippingapis.com /ShippingAPI.dll ?API=ExpressMailIntl &XML=(see below) 

https:// secure.shippingapis.com /ShippingAPI.dll ?API=ExpressMailIntlCertify &XML=(see below) 

USPS Web Tools Reference: International Shipping Labels Web Tools (Document Version 4.1) 5

2.1.2 

Request Diagram 







USPS Web Tools Reference: International Shipping Labels Web Tools (Document Version 

4.1) 12

2.1.3 Request Parameters 

Tag Name Occurs Description Type Validation 

ExpressMailIntlRequest 

required 

once 

(group) 

ExpressMailIntlRequest / 

@USERID 

required 

This attribute specifies your Web Tools ID. See the 

Developer's Guide for information on obtaining your 

USERID. 

string 


@PASSWORD 

optional For backward-compatibility; not validated. string 

ExpressMailIntlRequest / Option optional For future use. empty 

ExpressMailIntlRequest / Revision optional Use of value 2 required as of January 2011. 

string minLength=0 

pattern=\d{1} 

For example: 2 

pattern= 


ImageParameters 


FromFirstName 


FromMiddleInitial 


FromLastName 

optional For future use. empty 

required 

once 

optional 

required 

once 

First and Last Name must be sent. Maximum Length: 32 

characters total for First, Middle, and Last Names with 

space after first and middle name. 

For example: John 




For example: L 




For example: Doe 

USPS Web Tools Reference: International Shipping Labels Web Tools (Document Version 4.1) 13 

string 

string 

string 

maxLength=30 

minLength=1 

Restriction enforced via truncation 

maxLength=1 


maxLength=30 

minLength=1 

Restriction enforced via truncation



FromFirm 

optional 

Firm name; may be left blank. 

For example: 

string 

maxLength=32 

Use this tag for a suite or apartment number only. Either 



FromAddress1 

optional 

Address1 or Address2 is required. 

For example: 

string 

maxLength=32 

Use this tag for the primary address line. 



FromAddress2 

required 

once For example: 10 Elm Street 

 

string 

maxLength=32 

Use this tag for Puerto Rico only. ZIP Code prefixes 006 to 

009, if area is so designated. 


optional 

string maxLength=32 


FromUrbanization 

ExpressMailIntlRequest / FromCity required 

once 


FromState 


FromZip5 


FromZip4 


FromPhone 

required 

once 

required 

once 

optional 

required 

once 

For example: URB Caparra 

Ter 

For example: Anytown string maxLength=16 

Use 2-letter USPS abbreviation. 

minLength=1 

For example: ST 

string length=2 

Input tag exactly as presented, not all caps. 5 digits 

required. 


Input tag exactly as presented, not all caps. If value is 

entered, 4 digits required. This is the ZIP+4 extension. 


10 digits required (including area code), with no 

punctuation. Use format: 2125551234 



string 

string 

string 

whiteSpace=collapse 

length=5 

pattern=\d{5} 


length=4 

pattern=\d{4} 


length=10 

pattern=\d{10}



FromCustomsReference 

optional 

ExpressMailIntlRequest / ToName required 

once 

ExpressMailIntlRequest / ToFirm 


ToAddress1 


ToAddress2 


ToAddress3 

ExpressMailIntlRequest / ToCity 


ToProvince 

required 

once 

required 

once 

optional 

optional 

required 

once 

optional 

Enter a value for the "Sender's Customs Reference" that 

will appear on the label. The text entered is any reference 

number that the sender wishes to use. 

For example: 

 

Enter a value for the recipient's name. 

For example: Ms. C. P. Apple 

Enter a value for the recipient's firm. 

For example: 

Three address lines are provided, but only 1 is required. 

Use as many as needed for complete address. 

For example: Apartado 3068 



For example: 



For example: 

Recipient's city. 

For example: PUERTO VALLARTA 

Enter the province for the recipient. 

For example: JALISCO 





string 

maxLength=36 

minLength=1 



string 

maxLength=18 

minLength=1 

string maxLength=9



ToCountry 


ToPostalCode 


ToPOBoxFlag 

required 

once 

required 

once 

required 

once 

ExpressMailIntlRequest / ToPhone optional 

ExpressMailIntlRequest / ToFax optional 

ExpressMailIntlRequest / ToEmail optional 


ToCustomsReference 

optional 

The country name entered must match an entry from the 

USPS-approved International Index of Countries and 

Localities. See the Index of Countries and Localities. Using 

a country name not on the list will result in a request failure. 

For example: MEXICO 

Enter the postal code for the recipient. 


Indicates whether or not the To Address is a Post Office 

Box. 

For example: N 

No format checking is done on international phone 

numbers. Required when 

Y 

For example: 011 52 (322) 222- 

0069 

No format checking is done on international fax numbers. 

For example: 011 52 (322) 222-0074 

Complete valid e-mail address is required if tag is used. 

For example: cpapple@email.com 

Enter a value for the "Importer's Customs Reference" that 

will appear on the label. The text entered is any reference 

number that the recipient wishes to use. 

For example: Order 

#23432 




string 

string 

string 

string 

string 

enumeration=Y 

enumeration=N 

maxLength=30 


maxLength=30 


maxLength=30 


pattern=([\w\-\.]+)@(([\w-]+\.)+)[a-zA- 

Z]{2,4} 


maxLength=28 




NonDeliveryOption 


AltReturnAddress1 







optional 

optional 

optional 

optional 

optional 

In case package is undeliverable, enter one of the following: 

"RETURN" for package to be returned to 

above. "REDIRECT" to return package to address specified 

below in tags. "ABANDON" to dispose of 

undeliverable package. 

For example: 

RETURN 

Valid only with the "REDIRECT" value with the 

tag. Six address lines are provided 

but only one is required. Use as many as needed for 

complete address. 

For example: 





For example: 





For example: 





For example: 


string 

string 

string 

string 

string 

enumeration=RETURN 

enumeration=REDIRECT 

enumeration=ABANDON 

maxLength=30 


maxLength=30 


maxLength=30 


maxLength=30 








AltReturnCountry 


Container 


ShippingContents 


ShippingContents / ItemDetail 

optional 

optional 

optional 

optional 





For example: 






string 

string 

For example: 

Required when 

REDIRECT and 

required to be equal to 

string 

For Example: 

MEXICO 

Use FLATRATEENV or 

LEGALFLATRATEENV for flat 

rate envelopes. 

Otherwise, use to specify special containers or container 

attributes that may affect postage. 

Note: RECTANGULAR or NONRECTANGULAR must be 

indicated when LARGE. 

required 

once 

required 

once 

repeating 

up to 30 

times 

string 

(group) 

(group) 

maxLength=30 


maxLength=30 


default=VARIABLE 

enumeration=VARIABLE 

enumeration=FLATRATEENV 

enumeration=LEGALFLATRATEENV 

enumeration=FLATRATEBOX 

enumeration=RECTANGULAR 

enumeration=NONRECTANGULAR



ShippingContents / ItemDetail / 

Description 

required 

once 

Description of the item. 

For example: Policy guidelines 

document 

string 

maxLength=56 

minLength=1 




Quantity 

required 

once 

Quantity of the item. Integer value required. 


integer whiteSpace=collapse 

The data entered with this tag provides the value of the set 

of items. If the item is 2 boxes of 50 pens and the value of 

minExclusive=0 



Value 

required 

once 

each box is $10.00, "20.00" (2 boxes x $10.00) should be 

entered. If the value of each pen is .25 then "25.00" (100 

pens x .25) should be entered. 

decimal whiteSpace=collapse 




NetPounds 



NetOunces 



HSTariffNumber 

required 

once 

required 

once 

required 

once 

For example: 55.00 

Provide the pounds component of the weight of the 

individual item listed with . 


Provide the ounces component of the weight of the 



For commercial items only. If known, the HS tariff number 

(6-digit) must be based on the Harmonized Commodity 

Description and Coding System developed by the World 

Customs Organization. 




integer 

string 


maxLength=6 

pattern=\d{0,6}




CountryOfOrigin 


InsuredNumber 


InsuredAmount 

required 

once 

For commercial items only. Country of Origin means the 

country where the goods originated, e.g. were produced, 

manufactured, or assembled. It is recommended you supply 

this information and attach an invoice to the outside to 

accelerate customs clearance in processing the items. The 

country name entered must match an entry from the USPSapproved 

International Index of Countries and Localities or 

be "United States". http://pe.usps.gov/text/Imm/immctry.htm 

– click on the link for “International Country Listings”. Using 

a country name not on the list will result in a request failure. 

For example: United 

States 


string 


optional 

ExpressMailIntlRequest / Postage optional 


GrossPounds 


GrossOunces 

required 

once 

required 

once 

Use this tag for entering an insurance amount, if known. 


Use this tag for entering a postage amount, if known. If the 

tag is present, but the value is blank, the postage will be 

automatically calculated. 

empty length=0 

empty length=0 

For example: 

Gross pounds and ounces together represent the total 

package weight, including packing material. For example, a 

package weighing 3 lbs 8 ounces would have "3" entered 

here and "8" entered with the tag. The 

Web Tool will check for maximum shipping weight of 70 

pounds. Allowable weight may change based on the service 

used to send package and the destination country. 



Enter the ounces component of the total package weight 

with this tag. 


integer



ContentType 


ContentTypeOther 


Agreement 


Comments 


LicenseNumber 


CertificateNumber 


InvoiceNumber 


ImageType 


ImageLayout 

required 

once 

Specifies the content of the package or envelope. 

For example: 

DOCUMENTS 


string 

enumeration=MERCHANDISE 

enumeration=SAMPLE 

enumeration=GIFT 

enumeration=DOCUMENTS 


enumeration=OTHER 

optional Required when OTHER. string maxLength=15 


required 

once 

optional 

optional 

optional 

optional 

required 

once 

optional 

Requires a value of Y to print and 

in Signature Box along with Current 

Date (Central Time USA). Any other value returns an error. 

Enter any comments. For example: 

 

Enter license number, if known or if included in package. 

For example: LIC- 

24356879 

Enter certificate number, if known or if included in package. 

For example: CERT- 

97865342 

Enter invoice number, if known or if included in package. 

For example: INV- 

040903 

string 

For example: PDF string 

See section 2.2 Form Output Layout Control. 

For example: 

TRIMONEPERFILE 

enumeration=Y 

enumeration=N 





string 

enumeration=PDF 

enumeration=TIF 

enumeration=NONE 

default=ONEPERFILE 

enumeration=ONEPERFILE 

enumeration=ALLINONEFILE 

enumeration=TRIMONEPERFILE 

enumeration=TRIMALLINONEFILE

Tag Name Occurs Description 

Written to Postal Manifest Detail record. 

Type Validation 


CustomerRefNo 

optional 

For example: Ref 

#369246 

ZIP of Post Office where mailed if different from 



POZipCode 

optional 

. Written to Postal Manifest Detail record. Must 

be valid ZIP Code. 

string 


length=5 

pattern=\d{5} 


LabelDate 


EMCAAccount 


EMCAPassword 


HoldForManifest 

ExpressMailIntlRequest / EELPFC 


CommercialPrice 

optional 


Date the mail will enter the mail stream. No more than 3 

days in the future. Default is day of request. 

For example: 09/28/2010 


string 



optional 

optional 

repeating 

up to 1 

times 

optional 

Restricted use. Holds manifest record for possible inclusion 

in SCAN request. 

Exemption and Exclusion Legend or PFC Code. 

Please refer to the International Mail Manual for further 

information - http://pe.usps.gov/text/imm/immc5_007.htm. 

For example: 30.37a 

Indicates if commercial-base price should be returned. For 

commercial-base price eligibility, please reference the 

Domestic Mail Manual at http://pe.usps.com/. 

For example: False 

string 

string 


maxLength=10 

pattern=\d{1,2}/\d{1,2}/\d\d(\d\d)? 

enumeration=Y 

enumeration=N 


minLength=0 

maxLength=35 

boolean default=false


Use in conjunction with Revision tag with value of 2 to 

indicate and trigger new functionality. 


ExpressMailIntlRequest / Size 

ExpressMailIntlRequest / Length 

ExpressMailIntlRequest / Width 

ExpressMailIntlRequest / Height 

optional 

optional 

optional 

optional 

Defined as follows: 

REGULAR: Package dimensions are 12’’ or less; 

LARGE: Any package dimension is larger than 12’’. 

For example: REGULAR 



Value must be numeric. Units are inches. Required when 

ExpressMailIntlRequest/Size is LARGE. 













string 


enumeration=LARGE 

enumeration=REGULAR 

decimal minExclusive=0.0 

totalDigits=10 




totalDigits=10





ExpressMailIntlRequest / Girth 

ExpressMailIntlCertifyRequest 

optional 

required 

once 


ExpressMailIntlRequest/Size is LARGE, and 

ExpressMailIntlRequest/Container is NONRECTANGULAR. 


API=ExpressMailIntlCertify 

"Certify" signature is for testing and demonstration - does 

not produce a mailable label 




(alias)

2.1.4 Request Example 

 

 

2 

 

John 

L 

Doe 

 

Apt 204 

2711 Ordway St NW 

Washington 

DC 

20008 

5036 

3015551212 

Ms Joyce Browning 

 

5th floor 

2045 Royal Road 

 

St Paul 

 

France 


06570 

N 

4345551212 

4345559999 

b@aol.com 

Return 

NONRECTANGULAR 

 

 

Description 1 

1 

1.11 

1 

1 

123456 

Brazil 

 

 

Description 1 

1 

1.11 

1 

1 

123456 

Brazil 

 


Description 1 

1 

1.11 

1 

1 

123456 

Brazil 

 

 

Description 1 

1 

1.11 

1 

1 

123456 

Brazil 

 

 

Description 1 

1 

1.11 

1 

1 

123456 

Brazil 


 

17 

2 

Documents 

Y 

ExpressMailIntlCertify Comments 

TIF 

ALLINONEFILE 

20770 

 

N 

LARGE 

20.5 

7 

15 

40 

 


2.2 

Express Mail International Response 

2.2.1 Response Diagram 



2.2.2 Response Parameters 


ExpressMailIntlResponse 

required 

once 

(group) 

ExpressMailIntlResponse / 

Postage 

required 

once 

Postage amount xs:decimal 


TotalValue 

required 

once 

Value of all items being shipped xs:decimal 


SDRValue 

required 

once 

Special Drawing Right calculated on Total Value xs:decimal 


BarcodeNumber 

required 

once 

Mail service related barcode, may be empty xs:string 


LabelImage 

required 

once 

Encoded images of label (may be empty depending upon layout option 

selected) 

xs:string 


Page2Image 

required 

once 


selected) 

xs:string 


Page3Image 

required 

once 


selected) 

xs:string 


Page4Image 

required 

once 


selected) 

xs:string 


Page5Image 

required 

once 


selected) 

xs:string 


Page6Image 

required 

once 


selected) 

xs:string 


Prohibitions 

required 

once 

List of items prohibited from mailing based on country of destination xs:string 


Restrictions 

required 

once 

Restrictions on items being shipped based on country of destination xs:string 


Observations 

required 

once 

Additional mailing information based on country of destination xs:string 




Regulations 


AdditionalRestrictions 

ExpressMailIntlResponse / Notes 


InsuranceFee 


LogMessage 

ExpressMailIntlCertifyResponse 

required 

once 

required 

once 

required 

once 

Additional regulations for shipping to destination country xs:string 

Additional restrictions on items being shipped to destination country xs:string 

Express Mail International Notes xs:string 

optional decimal minExclusive=0.0 

maxInclusive=5000 

optional 

required 

once 

A text message for integrators of this API. It may contain additional 

information about this particular request/ response, or general information 

about the API or Web Tools. In typical implementations, whenever this tag 

is encountered, the message is written to the console log file for later 

analysis. 


string 

(alias)

2.2.3 

Tagged Label Diagram 


2.2.4 

Response Example 

 

 

110.00 

5.55 

3.65 

ECXXXXXXXXUS 

 

SUkqAAgAAAASAP4ABAABAAAAAAAAAAABBAABAAAArgYAAAEBBAABAAAAnQgAAAIBA... 

 

 

 

 

 

 

 

Arms, ammunition. Cigarette lighters using butane 

Bees, honey, and beeswax must be accompanied 

1. An air parcel post item may be addressed to a 

Country Code:FR Reciprocal Service Name: There 

 

 


3 Priority Mail International API 

3.1 Priority Mail International Request 








12345 




https:// secure.shippingapis.com /ShippingAPI.dll ?API=PriorityMailIntl &XML=(see below) 

https:// secure.shippingapis.com /ShippingAPI.dll ?API=PriorityMailIntlCertify &XML=(see below) 


3.1.2 Request Diagram 








USPS Web Tools Reference: International Shipping Labels Web Tools (Document Version 4.1) 

43

3.1.3 Request Parameters 


PriorityMailIntlRequest 

PriorityMailIntlRequest / 

@USERID 


@PASSWORD 


Option 


Revision 




FromFirstName 




FromLastName 

required 

once 

required 

Produces a Priority Mail International label with customs 

declaraction 



USERID. 


(group) 

NMTOKEN 

optional For backward compatibility; not validated. NMTOKEN 


required 

Use of value 2 required as of January 2011. 


string 


required 

once 

optional 

required 

once 













string 

string 

string 

maxLength=30 

minLength=1 


maxLength=1 


maxLength=30 

minLength=1 




FromFirm 


FromAddress1 


FromAddress2 




FromCity 


FromState 


FromZip5 


FromZip4 


FromPhone 

optional 

optional 

required 

once 

optional 

required 

once 

required 

once 

required 

once 

optional 

required 

once 


For example: 

Use this tag for a suite or apartment number only. Either 

Address1 or Address2 is required. 

For example: 


For example: 10 Elm Street 

 

Use this tag for Puerto Rico only. ZIP Code prefixes 006 

to 009, if area is so designated. 

For example: URB Caparra 

Ter 


string 

string 

string 

For example: Anytown string 


For example: ST 

Input tag exactly as presented, not all caps. 5 digits 

required. 


Input tag exactly as presented, not all caps. If value is 

entered, 4 digits required. This is the ZIP+4 extension. 






maxLength=32 


maxLength=32 


maxLength=32 

minLength=1 



maxLength=16 

minLength=1 

string length=2 

string 

string 

string 


length=5 

pattern=\d{5} 


length=4 

pattern=\d{4} 


length=10 

pattern=\d{10}


Enter a value for the "Sender's Customs Reference" that 

will appear on the label. The text entered is any 

reference number that the sender wishes to use. 



FromCustomsReference 


ToName 


ToFirm 


ToAddress1 


ToAddress2 


ToAddress3 


ToCity 


ToProvince 

optional 

required 

once 

required 

once 

required 

once 

optional 

optional 

required 

once 

optional 

For example: 

 

Note: ignored when specified is a flat rate 

envelope or small flat rate box (SMFLATRATEBOX, 

DXDBOX, LGVIDEOBOX) variation. 

Enter a value for the recipient's name. 


Enter a value for the recipient's firm. 

For example: 



For example: Apartado 

3068 



For example: 



For example: 









string 

maxLength=36 

minLength=1 



string 

maxLength=18 

minLength=1 

string maxLength=9



ToCountry 


ToPostalCode 


ToPOBoxFlag 


ToPhone 


ToFax 


ToEmail 


ToCustomsReference 

required 

once 

required 

once 

required 

once 

optional 

optional 

optional 

optional 



Localities. (http://pe.usps.gov/text/Imm/Immctry.htm - 

click on the link for "International Country Listings.") 

Using a country name not on the list will result in a 

request failure. 





Box. 




Y 

For example: 011 52 (322) 222- 

0069 

No format checking is done on international fax 

numbers. 

For example: 011 52 (322) 222-0074 

Complete valid e-mail address is required if tag is used. 


Enter a value for the "Recipient's Reference" that will 

appear on the label. The text entered is any reference 

number that the recipient wishes to use. 

For example: Order 

#23432 




string 

string 

string 

string 

string 

enumeration=Y 

enumeration=N 

maxLength=30 


maxLength=30 


maxLength=30 


pattern=([\w\-\.]+)@(([\w-]+\.))+[a-zA- 

Z]{2,4} 


maxLength=28 




NonDeliveryOption 





optional 

optional 

optional 

In case package is undeliverable, enter one of the 

following: "RETURN" for package to be returned to 

above. "REDIRECT" to return package 

to address specified below in tags. 

"ABANDON" to dispose of undeliverable package. 

For example: 

RETURN 





tag. Six address lines are 

provided but only one is required. Use as many as 

needed for complete address. 

For example: 

 








For example: 

 





string 

string 

string 

default=ABANDON 


enumeration=REDIRECT 

enumeration=ABANDON 

maxLength=30 


maxLength=30 














optional 

optional 

optional 

For example: 

 








For example: 

 








For example: 

 





string 

string 

string 

maxLength=30 


maxLength=30 


maxLength=30 











AltReturnCountry 

optional 

optional 

For example: 

 




Required when 

REDIRECT 

and required to be equal to 

For Example: 

MEXICO 





string 

string 

maxLength=30 




Container 




ShippingContents / 

ItemDetail 



ItemDetail / Description 

optional 

required 

once 

required 

once 

repeating 

up to 30 

times 

required 

once 

Use MDFLATRATEBOX or 

LGFLATRATEBOX or 

SMFLATRATEBOX or 

LGVIDEOBOX or 

DVDBOX for flat rate boxes, 

FLATRATEENV or 

LEGALFLATRATEENV or 

PADDEDFLATRATEENV or 

WINDOWFLATRATEENV or 

SMFLATRATEENV or 

GIFTCARDFLATRATEENV for 

flat rate envelopes. 

Otherwise, use to specify special containers or container 

attributes that may affect postage. 

Note: RECTANGULAR or NONRECTANGULAR must 

be indicated when LARGE. 

For the flat rate envelope and small flat rate box 

variations, gross weight must be 4 pounds or less and 

total value must be at most $400. 

When specified is a flat rate envelope or 

small flat rate box (SMFLATRATEBOX, DVDBOX, 

LGVIDEOBOX) variation, maxOccurs=”5”; that is, a 

maximum of five tags is permitted. 

Description of the item. 

For example: Policy guidelines 

document 


string 

(group) 

(group) 

string 

default=VARIABLE 

enumeration=VARIABLE 


enumeration=NONRECTANGULAR 

enumeration=LGFLATRATEBOX 

enumeration=MDFLATRATEBOX 

enumeration=SMFLATRATEBOX 

enumeration=FLATRATEBOX 

enumeration=LGVIDEOBOX 

enumeration=DVDBOX 

enumeration=FLATRATEENV 

enumeration=LEGALFLATRATEENV 

enumeration=PADDEDFLATRATEENV 

enumeration=WINDOWFLATRATEENV 

enumeration=SMFLATRATEENV 

enumeration=GIFTCARDFLATRATEENV 

maxLength=56 

minLength=1 

whiteSpace=collapse




ItemDetail / Quantity 

required 

once 



The data entered with this tag provides the value of the 

set of items. If the item is 2 boxes of 50 pens and the 

integer 





ItemDetail / Value 

required 

once 

value of each box is $10.00, "20.00" (2 boxes x $10.00) 

should be entered. If the value of each pen is .25 then 

"25.00" (100 pens x .25) should be entered. 

decimal 





ItemDetail / NetPounds 



ItemDetail / NetOunces 



ItemDetail / HSTariffNumber 

required 

once 

required 

once 

required 

once 








For commercial items only. If known, the HS tariff 

number (6-digit) must be based on the Harmonized 

Commodity Description and Coding System developed 

by the World Customs Organization. 

For example: 

490110 


integer 

decimal 

string 

default=0 


default=0.0 



maxLength=6 

pattern=\d{0,6}




ItemDetail / CountryOfOrigin 


Insured 


InsuredNumber 


InsuredAmount 


Postage 

required 

once 

optional 



manufactured, or assembled. It is recommended you 

supply this information and attach an invoice to the 

outside to accelerate customs clearance in processing 

the items. The country name entered must match an 

entry from the USPS-approved International Index of 

Countries and Localities or be "United States". 

(http://pe.usps.gov/text/Imm/Immctry.htm - click on the 

link for "International Country Listings.") Using a country 

name not on the list will result in a request failure. 

For example: United 

States 

Restricted use: authorized users may indicate with a 

value of Y that the item is insured for purposes of 

obtaining a barcode number from the insured range. All 

other users must specify N or omit. 


string 

string 


optional 

optional 

Use this tag for entering an insurance amount, if known. 

For example: 

100.00 




Use this tag for entering a postage amount, if known. If 

the tag is present, but the value is blank, the postage will 

be automatically calculated. 

For example: 

string 

decimal 

string 

decimal 

default=N 

enumeration=Y 

enumeration=N 

length=0 

length=0



GrossPounds 


GrossOunces 


ContentType 




Agreement 


Comments 

required 

once 

required 

once 

required 

once 

optional 

required 

once 

optional 


package weight, including packing material. For 

example, a package weighing 3 lbs 8 ounces would 

have "3" entered here and "8" entered with the 

tag. The Web Tool will check for 

maximum shipping weight of 70 pounds. Allowable 

weight may change based on the service used to send 

package and the destination country. 








decimal whiteSpace=collapse 

For example: 

DOCUMENTS 

Note: when specified is a flat rate envelope 

or small flat rate box (SMFLATRATEBOX, DXDBOX, 

LGVIDEOBOX) variation, RETURN is not a valid option. 

Required when OTHER. 

Maximum length enforced via truncation 

Requires a value of Y to print and 

in Signature Box along with Current 

Date (Central Time USA). Any other value returns an 

error. 

Enter any comments. 

For example: 


envelope. 

string 

string 

string 







maxLength=15 


enumeration=Y 

enumeration=N 

string maxLength=76


Enter license number, if known or if included in package. 



LicenseNumber 




InvoiceNumber 


ImageType 


ImageLayout 

optional 

optional 

optional 

required 

once 

optional 

For example: LIC- 

24356879 




Enter certificate number, if known or if included in 

package. 

For example: CERT- 

97865342 




Enter invoice number, if known or if included in package. 

For example: INV- 

040903 





See section 2.2 Form Output Layout Control. 

For example: 

TRIMONEPERFILE 





string 







enumeration=TRIMONEPERFILE 

enumeration=TRIMALLINONEFILE





CustomerRefNo 


POZipCode 


LabelDate 




EELPFC 

optional 

optional 

optional 

optional 

optional 

For example: Ref 

#369246 




ZIP of Post Office where mailed if different from 

. Written to Postal Manifest Detail record. 

Must be valid ZIP Code. 


Date the mail will enter the mail stream. No more than 3 

days in the future. Default is day of request. 


Restricted use. Holds manifest record for possible 

inclusion in SCAN request. 

Exemption and Exclusion Legend or PFC Code. Use in 

conjunction with Revision tag with value of 1 to indicate 

and trigger new functionality. 


information - 

http://pe.usps.gov/text/imm/immc5_007.htm. 

To activate check boxes use ”30.37a” or “30.37h”. 




string 

string 


length=5 

pattern=\d{5} 


maxLength=10 


enumeration=Y 

string 

enumeration=N 

string whiteSpace=collapse 

minLength=0 

maxLength=35



CommercialPrice 

PriorityMailIntlRequest / Size 


Length 


Width 


Height 


Girth 

optional 

optional 

optional 

optional 

optional 

optional 

Indicates if commercial-base price should be returned. 

For commercial-base price eligibility, please reference 

the Domestic Mail Manual at http://pe.usps.com/. 

For example: 

False 







Value must be numeric. Units are inches. Required 

when PriorityMailIntlRequest/Size is LARGE. 









when PriorityMailIntlRequest/Size is LARGE, and 

PriorityMailIntlRequest/Container is 

NONRECTANGULAR. 



boolean default=false 

string 

decimal 

decimal 

decimal 

decimal 




minExclusive=0.0 







totalDigits=10


PriorityMailIntlCertifyRequest required 

once 

API=PriorityMailIntlCertify 

"Certify" signature is for testing and demonstration - 

does not produce a mailable label 


(alias)


 

 

2 

 

John 

L 

Doe 

USPS 

Suite 10000 

475 Lenfant 

Washington 

DC 

20260 

2025551212 

Ms. Joyce Browning 

XYZ Corp. 

5th Floor 

Frankfurter Allee 1 

 

Munich 

 

Germany 

83497 


N 

5155551212 

8884865188 

b@aol.com 

Return 

VARIABLE 

 

 

 

 

 

 

Description 1 

1 

1.11 

1 

1 

123456 

Brazil 

Description 2 

2 

2.22 

2 

2 

234567 

Canada 


N 

3 

3 

Merchandise 

Y 

PriorityMailIntl Comments 

TIF 

ALLINONEFILE 

20770 

4/23/2007 

N 

30.37a 

LARGE 

10.5 

5.5 

5.5 

35.5 

 


3.2 

Priority Mail International Response 




3.2.2 

Response Parameters 

PriorityMailIntlResponse 


PriorityMailIntlResponse / Postage 

PriorityMailIntlResponse / TotalValue 

PriorityMailIntlResponse / SDRValue 

PriorityMailIntlResponse / BarcodeNumber 

PriorityMailIntlResponse / LabelImage 

PriorityMailIntlResponse / Page2Image 





PriorityMailIntlResponse / Prohibitions 

PriorityMailIntlResponse / Restrictions 

PriorityMailIntlResponse / Observations 

PriorityMailIntlResponse / Regulations 

required 

once 

required 

once 

required 

once 

required 

once 

required 

once 

required 

once 

required 

once 

required 

once 

required 

once 

required 

once 

required 

once 

required 

once 

required 

once 

required 

once 

required 

once 


(group) 

Postage amount decimal 

Value of all items being shipped decimal 

Special Drawing Right calculated on Total Value decimal 

Mail service related barcode, may be empty string 

Encoded images of label (may be empty depending upon layout 

option selected) 











List of items prohibited from mailing based on country of 

destination 

Restrictions on items being shipped based on country of 

destination 

base64Binary 

base64Binary 

base64Binary 

base64Binary 

base64Binary 

base64Binary 

string 

string 

Additional mailing information based on country of destination string 

Additional regulations for shipping to destination country string

PriorityMailIntlResponse / 


PriorityMailIntlResponse / 

ParcelIndemnityCoverage 


required 

once 

required 

once 

Additional restrictions on items being shipped to destination 

country 


string 

Indemnity value decimal 

PriorityMailIntlResponse / InsuranceFee optional decimal 

PriorityMailIntlResponse / LogMessage optional 

PriorityMailIntlCertifyResponse 

required 

once 

A text message for integrators of this API. It may contain 

additional information about this particular request/response, or 

general information about the API or Web Tools. In typical 

implementations, whenever this tag is encountered, the message 

is written to the console log file for later analysis. 

string 

(alias) 


maxInclusive=5000

3.2.3 



3.2.4 

Response Example 

 

 

37.15 

3.33 

2.19 

CJXXXXXXXXXUS 

SUkqAAgAAAASAP4ABAABAAAAAAAAAAABBAABAAAArgYAAAEBBAABAAAAnQgAAAIB 

 

 

 

 

 

 

 

Absinthe. Articles bearing political or religious notations on the address si 

Importation of medicines requires special authorization by German authorities. 

1. An air parcel post item may be addressed to a street address or to a pos 

Country Code: DE Reciprocal Service Name: There is no reciprocal service. 

 

73.23 

 


4 

First Class Mail International API 

4.1 First Class Mail International Request 








12345 




https:// secure.shippingapis.com /ShippingAPI.dll ?API=FirstClassMailIntl &XML=(see below) 

https:// secure.shippingapis.com /ShippingAPI.dll ?API=FirstClassMailIntlCertify &XML=(see below) 


4.1.2 

Request Diagram 







4.1.3 

Request Parameters 


FirstClassMailIntlRequest 

FirstClassMailIntlRequest / 

@USERID 


@PASSWORD 


Option 


Revision 




FromFirstName 



required 

once 

required 



USERID. 


(group) 

NMTOKEN 

optional For backward compatibility; not validated. NMTOKEN 


required 

Use of value 2 required as of January 2011. 


string 


required 

once 

optional 









string 

string 

maxLength=30 

minLength=1 


maxLength=1 

whiteSpace=collapse



FromLastName 


FromFirm 


FromAddress1 


FromAddress2 




FromCity 


FromState 


FromZip5 

required 

once 

required 

once 

optional 

required 

once 

optional 

required 

once 

required 

once 

required 

once 






For example: 

Use this tag for a suite or apartment number only. 

For example: 


For example: 

10 Elm Street 

Use this tag for Puerto Rico only. ZIP Code prefixes 006 to 

009, if area is so designated. 

For example: 

URB Caparra 

Ter 

Use this tag to specify originating city. 

For example: Anytown 


For example: AK 

Five-digit valid ZIP code required. 



string 

string 

string 

string 

string 

string 

string 

string 

maxLength=30 

minLength=1 


maxLength=32 


maxLength=32 


maxLength=32 

minLength=1 


maxLength=32 


maxLength=16 

minLength=1 


length=2 



length=5 

pattern=\d{5}



FromZip4 


FromPhone 


ToName 


ToFirm 


ToAddress1 


ToAddress2 


ToAddress3 

optional 

required 

once 

required 

once 

required 

once 

required 

once 

optional 

optional 

If value is entered, four digits are required. Must be a valid 

ZIP+4 extension. 





Enter a value for the recipient's name; may be left blank if 

Firm name is provided. 


Enter a value for the recipient's firm; may be left blank if 

Recipient name is provided. 

For example: 

Three address lines are provided, but only one is required. 


For example: 

Apartado 3068 



For example: 



For example: 


string 

string 

string 

string 

string 

string 

string 


length=4 

pattern=\d{4} 


length=10 

pattern=\d{10} 

maxLength=36 


maxLength=36 


maxLength=36 

minLength=1 


maxLength=36 


maxLength=36 

whiteSpace=collapse



ToCity 


ToProvince 


ToCountry 


ToPostalCode 


ToPOBoxFlag 


ToPhone 


ToFax 

required 

once 

optional 

required 

once 

required 

once 

required 

once 

optional 

optional 







Localities or be "United States". 

(http://pe.usps.gov/text/Imm/Immctry.htm - click on the link 

for "International Country Listings.") Using a country name 

not on the list will result in a request failure. 





Box. 




FirstClassMailIntlRequest[ToPOBoxFlag='Y']. 

For example: 

011 52 (322) 222-0069 

No format checking is done on international fax numbers. 

For example: 011 52 (322) 222-0074 


string 

string 

string 

string 

string 

string 

string 

maxLength=18 

minLength=1 


maxLength=9 


minLength=1 


maxLength=9 



enumeration=Y 

enumeration=N 

maxLength=30 


maxLength=30 

whiteSpace=collapse



ToEmail 


FirstClassMailType 




ShippingContents / ItemDetail 



Description 



Quantity 



Value 

optional 

optional 

required 

once 

required 

once 

repeating 

up to 5 

times 

required 

once 

required 

once 

required 

once 

One single, complete, and valid e-mail address is required 

if tag is used. 


Used to determine the postage rate. See also 

FirstClassMailIntlRequest/Machinable. 

For example: 

LETTER 

Description of the item. Non-descriptive wording such as 

'Gift' will result in an error. 

For example: 

Policy guidelines document 



The data entered with this tag provides the value of the set 

of items. If the item is 2 boxes of 50 pens and the value of 

each box is $10.00, "20.00" (2 boxes x $10.00) should be 

entered. If the value of each pen is .25 then "25.00" (100 

pens x .25) should be entered. 



string 

string 

(group) 

(group) 

string 

integer 

decimal 

maxLength=30 


pattern=([\w\-\.]+)@(([\w-]+\.))+[a-zA- 

Z]{2,4} 

default=PARCEL 


enumeration=LETTER 

enumeration=FLAT 

enumeration=PARCEL 

maxLength=56 

minLength=1 




maxExclusive=1000 



maxExclusive=100000




NetPounds 



NetOunces 



HSTariffNumber 



CountryOfOrigin 

required 

once 

required 

once 

required 

once 

required 

once 


individual item listed within this ItemDetail. 



individual item listed within this ItemDetail. 


For commercial items only. If known, the HS tariff number 

(6-digit) must be based on the Harmonized Commodity 

Description and Coding System developed by the World 

Customs Organization. 

For example: 

490110 



manufactured, or assembled. It is recommended you 

supply this information and attach an invoice to the outside 

to accelerate customs clearance in processing the items. 



Localities or be "United States". 

(http://pe.usps.gov/text/Imm/Immctry.htm - click on the link 

for "International Country Listings.") Using a country name 

not on the list will result in a request failure. 

For example: 

United States 


integer 

decimal 

string 

string 

default=0 


minInclusive=0 

default=0.0 




maxLength=6 

minLength=0 

pattern=\d{6} 

pattern=\d{0} 


minLength=0



Postage 


GrossPounds 


GrossOunces 


Machinable 


ContentType 



optional 

required 

once 

required 

once 

optional 

required 

once 

optional 

Use this tag for entering a postage amount, if known. If the 

tag is present, but the value is blank, the postage will be 

automatically calculated. 

For example: 


package weight, including packing material. For example, a 

package weighing 3 lbs 8 ounces would have "3" entered 

here and "8" entered with the "GrossOunces" tag. The 

Web Tool will check for maximum shipping weight of 70 

pounds. Allowable weight may change based on the 

service used to send package and the destination country. 





Indicates whether or not the item is machinable. A 

surcharge is applied to a First-Class Mail International item 

if it has one or more non-machinable characteristics. See 

International Mail Manual (IMM) Section 241 for more 

information. 

For example: false 


For example: 

DOCUMENTS 

Required when 

FirstClassMailIntlRequest[ContentType='OTHER']. 


string 

decimal 

integer 

decimal 

boolean 

string 

string 

length=0 






default=true 








maxLength=15 

whiteSpace=collapse



Agreement 


Comments 


LicenseNumber 




InvoiceNumber 


ImageType 


ImageLayout 


CustomerRefNo 

required 

once 

Indicates the requestor's agreement to terms and 

conditions of mailing. Requires a value of Y to print and in 

Signature Box along with Current Date (Central Time 

USA). Any other value returns an error. 


string 

optional For future use. string 




required 

once 

optional 

optional 


Specified whether the pages are to be returned one per file 

or all in one file. The current FCMI label is one page so this 

tag has no effect. 

For example: 

ONEPERFILE 


For example: 

Ref #369246 

string 


enumeration=Y 

maxLength=76 


maxLength=24 


maxLength=24 


maxLength=24 










string maxLength=30



LabelDate 




EELPFC 


Container 

FirstClassMailIntlRequest / Size 


Length 

optional 

optional 

optional 

Date the mail will enter the mail stream. No more than 

three days in the future. Default is day of request. 


Restricted use. Holds manifest record for possible inclusion 

in SCAN request. 

Exemption and Exclusion Legend or PFC Code. Currently 

optional, in the future it may be required for use. 


information - http://pe.usps.gov/text/imm/immc5_007.htm. 

To activate check boxes use ”30.37a” or “30.37h”. 


When 

FirstClassMailIntlRequest[FirstClassMailType='PARCEL'] 

and [Size=’LARGE’], use to specify special containers or 

optional 

container attributes that may affect postage. 

optional 

optional 

For example: RECTANGULAR 

May be left blank in situations that do not require a Size: 

(FirstClassMailIntlRequest[FirstClassMailType='LETTER’ 

or ‘FLAT']). 






FirstClassMailIntlRequest/Size is LARGE. 



string 

string 


maxLength=10 


enumeration=Y 

enumeration=N 

string whiteSpace=collapse 

minLength=0 

maxLength=35 

string 

string 

decimal 



enumeration=NONRECTANGULAR 





totalDigits=10



Width 


Height 


Girth 

optional 

optional 

optional 

FirstClassMailIntlCertifyRequest required 

once 








FirstClassMailIntlRequest/Size is LARGE, and 

FirstClassMailIntlRequest/Container is 

NONRECTANGULAR. 


API=FirstClassMailIntlCertify 

"Certify" signature is for testing and demonstration - does 

not produce a mailable label 


decimal 

decimal 

decimal 

(alias) 






totalDigits=10


 

 

2 

 

John 

C 

Doe 

USPS 

Suite 10000 

475 Lenfant 

Washington 

DC 

20260 

2025551212 

Jane Smith 

 

 

5th floor 

789 Universal Dr 

Ottawa 

Canada 

K1A0A1 

N 


5555555555 

88888888888888 

b@aol.com 

PARCEL 

 

 

Description 1 

1 

1.11 

1 

1 

123456 

Brazil 

 

 

Description 2 

2 

2.22 

0 

2 

234567 

Canada 

 

 

3 

2 


false 

GIFT 

Y 

FirstClassMailIntl Comments 

TIF 

ONEPERFILE 

N 

30.37a 

RECTANGULAR 

REGULAR 

10.5 

5.5 

5.5 

5.5 

 


4.2 

First Class Mail International Response 



4.2.2 

Response Parameters 

FirstClassMailIntlResponse 


FirstClassMailIntlResponse / Postage 

FirstClassMailIntlResponse / TotalValue 

FirstClassMailIntlResponse / 

BarcodeNumber 

FirstClassMailIntlResponse / LabelImage 

required 

once 

required 

once 

required 

once 

required 

once 

required 

once 

FirstClassMailIntlResponse / Page2Image required 

once 

FirstClassMailIntlResponse / Page3Image required 

once 

required 

FirstClassMailIntlResponse / Prohibitions 

once 

required 

FirstClassMailIntlResponse / Restrictions 

once 

FirstClassMailIntlResponse / 

Observations 

FirstClassMailIntlResponse / Regulations 

FirstClassIntlResponse / 


FirstClassMailIntlCertifyResponse 

required 

once 

required 

once 

required 

once 

required 

once 


(group) 

Postage amount decimal 

Value of all items being shipped decimal 

Mail service related barcode, may be empty string 

Encoded images of label. (may be empty depending upon layout 

selection or items shipped) 





List of items prohibited from mailing based on country of destination string 

Restrictions on items being shipped based on country of destination string 

Additional mailing information based on country of destination string 

Additional regulations for shipping to destination country string 

Additional restrictions on items being shipped to destination country string 

base64Binary 

base64Binary 

base64Binary 

(alias)

4.2.3 



4.2.4 Response Example 

 

 

25.15 

3.33 

LJXXXXXXXXXUS 

SUkqAAgAAAASAP4ABAABAAAAAAAAAAABBAABAAAArgYAAAEBB= 

 

 

Arms, ammunition, weapons. Articles in hermetical. 

The importation of personal articles is limited ts 

Articles that do not meet the requirements mentio. 

Country Code: CN Reciprocal Service Name: Internal

International Shipping Labels

Create successful ePaper yourself

Delete template?

Save as template?