1.0 Introduction to Web Tools

This document contains a Reference Guide to the eVS international label APIs: Priority Mail Express International, Priority Mail International, Global Express Guaranteed (see section IV for limitations) and First Class Mail International (First Class Package International Service). See the Developer’s Guide 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.

Note: The Request Parameter sections present the XML input tags for generating live requests along with 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 process 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:

In this instance, you will replace “2” with the weight in pounds for the package.

1.1 Before you get started:

Whether you are a new or existing mailer, USPS strongly suggests a conversation with you to discuss your business requirements so your account will be properly configured. To initiate this conversation please contact the National Customer Support Center (NCSC) at 877-264-9693 Option 4 and request a referral to an Operations Integration Specialist (OIS) and Technical Integration Specialist (TIS). USPS will align the appropriate team to assist with swift onboarding.

Depending on your needs, your account may be configured in many flexible ways; however, each account will be configured with credentials in a master/child relationship. Minimally, credentials will be established as follows:

o A master Mailer ID is created

§ Child Mailer IDs are created for each origin site and may be created as needed by the requirements of your business units and brands.

o A permit number is created

§ Additional permit numbers may be created as needed by the requirements of your business units and brands

o A CAPS Debit account is created for payment processing

§ Additional CAPS Debit accounts may be created as needed

Your Operations Integration Specialist and Technical Integration Specialist will be involved at the local and national levels to ensure successful launch and introduction to appropriate production support teams.

For information on registering and getting started with Web Tools, please refer to the Step-By-Step guide found on the Technical Documentation section of the Web Tools page on usps.com/webtools.

Label APIs require extra permissions; contact the Internet Customer Care Center (https://Emailus.usps.com/) to request access. Indicate “Label API Access” in the subject line and explain in the body of the email:

1. How the shipper intends to purchase and apply postage to the labels

2. If the label image provided by the API will be modified in any way by the shipper or the software

2.0 eVS Priority Mail Express International Label API

2.1 Overview

The eVS Priority Mail Express International Label API lets customers generate eVS Priority Mail Express International labels given the weight and dimensions of the item.

Note: Scan form is eligible for eVS if the HoldForManifest is Y (Yes).

2.2 API Signature

*Scheme*	*Host*	*Path*	*API*	*XML*
https://	secure.shippingapis.com	/ShippingAPI.dll?	API=eVSExpressMailIntl	&XML=(see Tag Descriptions below)
https://	secure.shippingapis.com	/ShippingAPI.dll?	API=eVSExpressMailIntlCertify	&XML=(see Tag Descriptions below)

Note: The “eVSExpressMailIntlCertify” API signature is for testing purposes and will not generate usable labels and barcodes.

2.3 Request Descriptions

Tag Name	Occurs	Description	Type	Validation
eVSExpressMailIntlRequest	required		(group)
eVSExpressMailIntlRequest / USERID	required	This attribute specifies your Web Tools ID. See the Developer's Guide for information on obtaining your USERID.	NMTOKEN
eVSExpressMailIntlRequest / PASSWORD	optional	For backward compatibility; not validated.	string
eVSExpressMailIntlRequest / APPID	optional		NMTOKEN
eVSExpressMailIntlRequest / Option	optional	For future use.	empty
eVSExpressMailIntlRequest / Revision	optional	Use of value 2 required as of January 2011. For example: <Revision>2</Revision>	string	minLength=0 pattern=\d{1} pattern=
eVSExpressMailIntlRequest / ImageParameters	optional	Groups alternate image options.	(group)
eVSExpressMailIntlRequest / ImageParameters / ImageParameter	Optional, repeating up to 3 times	Returns alternate label image. Only alternate 4’’x6’’ size label image may be requested at this time. · 4X6LABEL (4X6 on a full page 8.5/11” background) · 4X6LABELL (Landscape – true size 4X6; image rotated, not on an 8.5 x 11 background page) · 4X6LABELP (Portrait – true size 4X6, not on an 8.5 x 11 background page) For example: <ImageParameter>4X6LABEL</ImageParameter>	string	Enumerations= 4X6LABEL 4X6LABELL 4X6LABELP
eVSExpressMailIntlRequest / FromFirstName	optional	Both FromFirstName and FromLastName are required if FromFirmName is left blank. Maximum Length: 32 characters total for First, Middle, and Last Names with space after first and middle name. For example: <FromFirstName>John</FromFirstName>	string	maxLength=30 minLength=0
eVSExpressMailIntlRequest / FromMiddleInitial	optional	Middle Initial. Maximum Length: 32 characters total for First, Middle, and Last Names with space after first and middle name. For example: <FromMiddleInitial>L</FromMiddleInitial>	string	maxLength=1
eVSExpressMailIntlRequest / FromLastName	optional	Both FromFirstName and FromLastName are required if FromFirmName is left blank. Maximum Length: 32 characters total for First, Middle, and Last Names with space after first and middle name. For example: <FromLastName>Doe</FromLastName>	string	maxLength=30 minLength=0
eVSExpressMailIntlRequest / FromFirm	optional	FromFirm is required if FromFirstName and FromLastName are left blank. For example: <FromFirm></FromFirm>	string	maxLength=32
eVSExpressMailIntlRequest / FromAddress1	optional	Use this tag for a suite or apartment number only. Either Address1 or Address2 is required. For example: <FromAddress1/>	string	maxLength=32
eVSExpressMailIntlRequest / FromAddress2	required	Use this tag for the primary address line. For example: <FromAddress2>10 Elm Street </FromAddress2>	string	maxLength=32
eVSExpressMailIntlRequest / FromUrbanization	optional	Use this tag for Puerto Rico only. ZIP Code prefixes 006 to 009, if area is so designated. For example: <FromUrbanization>URB Caparra Ter</FromUrbanization>	string	maxLength=32
eVSExpressMailIntlRequest / FromCity	required	For example: <FromCity>Anytown</FromCity>	string	maxLength=16 minLength=1
eVSExpressMailIntlRequest / FromState	required	Use 2-letter USPS state abbreviation. For example: <FromState>ST</FromState>	string	length=2
eVSExpressMailIntlRequest / FromZip5	required	Input tag exactly as presented, not all caps. 5 digits required. For example: <FromZip5>01234</FromZip5>	string	whiteSpace=collapse length=5 pattern=\d{5}
eVSExpressMailIntlRequest / FromZip4	optional	Input tag exactly as presented, not all caps. If value is entered, 4 digits required. This is the ZIP+4 extension. For example: <FromZip4>5678</FromZip4>	string	whiteSpace=collapse length=4 pattern=\d{4}
eVSExpressMailIntlRequest / FromPhone	required	10 digits required (including area code), with no punctuation. Use format: 2125551234 For example: <FromPhone>5555555555</FromPhone>	string	whiteSpace=collapse length=10 pattern=\d{10}
eVSExpressMailIntlRequest / FromCustomsReference	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: <FromCustomsReference></FromCustomsReference>	string	maxLength=30
eVSExpressMailIntlRequest / ToName	optional	Deprecated. See “ToFirstName” and “ToLastName” tags.	string	maxLength=36
eVSExpressMailIntlRequest / ToFirstName	optional	Both ToFirstName and ToLastName are required if ToFirm is left blank. For example: <ToFirstName>John</ToFirstName>	string	maxLength=30
eVSExpressMailIntlRequest / ToLastName	optional	Both ToFirstName and ToLastName are required if ToFirm is left blank. For example: <ToLastName>Doe</ToLastName>	string	maxLength=30
eVSExpressMailIntlRequest / ToFirm	optional	ToFirm is required if ToFirstName and ToLastName are left blank. For example: <ToFirm></ToFirm>	string	maxLength=36
eVSExpressMailIntlRequest / ToAddress1	required	Three address lines are provided, but only 1 is required. Use as many as needed for complete address. For example: <ToAddress1> Apartado 3068</ToAddress1>	string	maxLength=36 minLength=1
eVSExpressMailIntlRequest / ToAddress2	optional	Three address lines are provided, but only 1 is required. Use as many as needed for complete address. For example: <ToAddress2></ToAddress2>	string	maxLength=36
eVSExpressMailIntlRequest / ToAddress3	optional	Three address lines are provided, but only 1 is required. Use as many as needed for complete address. For example: <ToAddress3></ToAddress3>	string	maxLength=36
eVSExpressMailIntlRequest / ToCity	required	Recipient's city. For example: <ToCity>PUERTO VALLARTA</ToCity>	string	maxLength=18 minLength=1
eVSExpressMailIntlRequest / ToProvince	optional	Enter the province for the recipient. For example: <ToProvince>JALISCO</ToProvince>	string	maxLength=9
eVSExpressMailIntlRequest / ToCountry	required	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: <ToCountry>MEXICO</ToCountry>	string	minLength=1
eVSExpressMailIntlRequest / ToPostalCode	required	Enter the postal code for the recipient. For example: <ToPostalCode>46807</ToPostalCode>	string	maxLength=9
eVSExpressMailIntlRequest / ToPOBoxFlag	required	Indicates whether or not the To Address is a Post Office Box. For example: <ToPOBoxFlag>N</ToPOBoxFlag>	string	enumeration=Y enumeration=N
eVSExpressMailIntlRequest / ToPhone	optional	No format checking is done on international phone numbers. Required when <ToPOBoxFlag>Y</ToPOBoxFlag> For example: <ToPhone>011 52 (322) 222-0069</ToPhone>	string	maxLength=30
eVSExpressMailIntlRequest / ToFax	optional	No format checking is done on international fax numbers. For example: <ToFax>011 52 (322) 222-0074</ToFax>	string	maxLength=30
eVSExpressMailIntlRequest / ToEmail	optional	Complete valid e-mail address is required if tag is used. For example: <ToEmail>cpapple@email.com</ToEmail>	string	maxLength=30 whiteSpace=collapse pattern=([\w\-\.]+)@(([\w-]+\.)+)[a-zA-Z]{2,4}
eVSExpressMailIntlRequest / ImportersReferenceNumber	optional	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: <ToCustomsReference>Order 23432</ToCustomsReference>	string	maxLength=28
eVSExpressMailIntlRequest / NonDeliveryOption	optional	In case package is undeliverable, enter one of the following: "RETURN" for package to be returned to <FromAddress> above. "REDIRECT" to return package to address specified below in <AltReturnâ€¦> tags. "ABANDON" to dispose of undeliverable package. For example: <NonDeliveryOption>RETURN</NonDeliveryOption>	string	enumeration=RETURN enumeration=REDIRECT enumeration=ABANDON
eVSExpressMailIntlRequest / RedirectName	optional	Enter a value for the recipient's name.	string	minOccurs=0
eVSExpressMailIntlRequest / RedirectEmail	optional	Complete valid e-mail address is required if tag is used.	string	minOccurs=0
eVSExpressMailIntlRequest / RedirectSMS	optional	This value must be a syntactically-valid SMS number.	string	minOccurs=0
eVSExpressMailIntlRequest / RedirectAddress	optional	Enter the redirect address. This is a free form field.	string	minOccurs=0 maxLength=48
eVSExpressMailIntlRequest / RedirectCity	optional	Redirect city. For example: < RedirectCity >ANYTOWN</ RedirectCity >	string	minLength=0 maxLength=21
eVSExpressMailIntlRequest / RedirectState	optional	Redirect state. For example: < RedirectState >MN</ RedirectState >	string	minLength=0 pattern=\w{2}
eVSExpressMailIntlRequest / RedirectZipCode	optional	Redirect ZIP code. For example: < RedirectZipCode >12345</RedirectZipCode>	string	minLength=0 pattern=\d{5}
eVSExpressMailIntlRequest / RedirectZip4	Optional	Redirect ZIP+4 extension. For example: < RedirectZip4>01234</ RedirectZip4>	string	minLength=0
eVSExpressMailIntlRequest / Container	optional	Uses validate enumeration.	string	default=VARIABLE enumerations= · VARIABLE · FLATRATEENV · LEGALFLATRATEENV · PADDEDFLATRATEENV
eVSExpressMailIntlRequest / ShippingContents	required		(group)
eVSExpressMailIntlRequest / ShippingContents / ItemDetail	required repeating up to 30 times		(group)	maxOccurs=”30"
eVSExpressMailIntlRequest / ShippingContents / ItemDetail / Description	required	Description of the item. For example: <Description>Policy guidelines document</Description>	string	maxLength=30 minLength=1 whiteSpace=collapse
eVSExpressMailIntlRequest / ShippingContents / ItemDetail / Quantity	required	Quantity of the item. Integer value required. For example: <Quantity>1</Quantity>	integer	minInclusive value="1" maxInclusive value="999"
eVSExpressMailIntlRequest / ShippingContents / ItemDetail / Value	required	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. For example: <Value>55.00</Value>	decimal	whiteSpace=collapse minExclusive=0
eVSExpressMailIntlRequest / ShippingContents / ItemDetail / NetPounds	required	Provide the pounds component of the weight of the individual item listed with <Description>. For example: <NetPounds>1</NetPounds>	integer	whiteSpace=collapse default=0
eVSExpressMailIntlRequest / ShippingContents / ItemDetail / NetOunces	required	Provide the ounces component of the weight of the individual item listed with <Description>. For example: <NetOunces>5</NetOunces>	decimal	default="0.0"
eVSExpressMailIntlRequest / ShippingContents / ItemDetail / HSTariffNumber	required	For commercial items only. If known, the HS tariff number must be based on the Harmonized Commodity Description and Coding System developed by the World Customs Organization. For example: <HSTariffNumber>490110</HSTariffNumber>	string	whiteSpace=collapse maxLength=12 pattern=\d{0,12}
eVSExpressMailIntlRequest / ShippingContents / ItemDetail / CountryOfOrigin	required	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 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. See Appendix A for Abbrevations. For example: <CountryOfOrigin>United States</CountryOfOrigin>	string
eVSExpressMailIntlRequest / InsuredNumber	optional	For backward-compatibility; not validated.	string
eVSExpressMailIntlRequest / InsuredAmount	optional	Use this tag for entering an insurance amount, if known. For example: <InsuredAmount>100.00</InsuredAmount>	string	length=0
eVSExpressMailIntlRequest / Postage	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: <Postage></Postage> or <Postage>10.50</Postage>	string	length=0
eVSExpressMailIntlRequest / GrossPounds	required	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 <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. For example: <GrossPounds>4</GrossPounds>	integer	whiteSpace=collapse
eVSExpressMailIntlRequest / GrossOunces	required	Enter the ounces component of the total package weight with this tag. For example: <GrossOunces>0</GrossOunces>	integer	maxLength=3
eVSExpressMailIntlRequest / ContentType	required	Specifies the content of the package or envelope. For example: <ContentType>DOCUMENTS</ContentType> Note: Enumerations are case sensitive “NonnegotiableDocument” and “Documents” both signify mailable non-negotiable documents and are insured automatically for up to $100, though Insurance will not be returned as an extra service. Additional Insurance cannot be purchased. Any non-document ContentType values are insured automatically for up to $200. Additional Insurance can be purchased for values $200 and greater.	string	enumerations= · MERCHANDISE · SAMPLE · GIFT · DOCUMENTS · RETURN · HUMANITARIAN · DANGEROUSGOODS · CrematedRemains · NonnegotiableDocument · PHARMACUTICALS · MEDICALSUPPLIES · OTHER
eVSExpressMailIntlRequest / ContentTypeOther	optional	Required when <ContentType>OTHER<ContentType>.	string	maxLength=15 whiteSpace=collapse
eVSExpressMailIntlRequest / Agreement	required	Requires a value of Y to print <FromFirstName/> and <FromLastName/> in Signature Box along with Current Date (Central Time USA). Any other value returns an error.	string	enumeration=Y enumeration=N
eVSExpressMailIntlRequest / Comments	optional	Enter any comments. For example: <Comments></Comments>	string	maxLength=76
eVSExpressMailIntlRequest / LicenseNumber	optional	Enter license number, if known or if included in package. For example: <LicenseNumber>LIC-24356879</LicenseNumber>	string	maxLength=24
eVSExpressMailIntlRequest / CertificateNumber	optional	Enter certificate number, if known or if included in package. For example: <CertificateNumber>CERT-97865342</CertificateNumber>	string	maxLength=24
eVSExpressMailIntlRequest / InvoiceNumber	optional	Enter invoice number, if known or if included in package. For example: <InvoiceNumber>INV-040903</InvoiceNumber>	string	maxLength=24
eVSExpressMailIntlRequest / ImageType	required	For example: <ImageType>PDF</ImageType>	string	enumeration=PDF enumeration=TIF enumeration=NONE
eVSExpressMailIntlRequest / ImageLayout	optional	Controls how the multipage form is returned in the response tags. "ONEPERFILE" returns one page per response tag while “ALLINONEFILE” returns all pages in a single response tag. The “TRIM” options conserve page space if possible by combining two form parts on a single page. For example: <ImageLayout>ONEPERFILE<ImageLayout>	string	default=ONEPERFILE enumerations= ONEPERFILE ALLINONEFILE TRIMONEPERFILE TRIMALLINONEFILE
eVSExpressMailIntlRequest / CustomerRefNo	optional	Written to Postal Manifest Detail record. For example: <CustomerRefNo>Ref 369246</CustomerRefNo>	string	maxLength=30
eVSExpressMailIntlRequest / CustomerRefNo2	optional	Written to Postal Manifest Detail record. For example: <CustomerRefNo2>ACT369246</CustomerRefNo2>	string	maxLength=30
eVSExpressMailIntlRequest / POZipCode	optional	ZIP of Post Office where mailed if different from <FromZip5/>. Written to Postal Manifest Detail record. Must be valid ZIP Code. For example: <POZipCode>00962</POZipCode>	string	whiteSpace=collapse length=5 pattern=\d{5}
eVSExpressMailIntlRequest / LabelDate	optional	Date the mail will enter the mail stream. No more than 3 days in the future. Default is day of request. For example: <LabelDate>09/28/2010</LabelDate>	string	whiteSpace=collapse maxLength=10 pattern=\d{1,2}/\d{1,2}/\d\d(\d\d)?
eVSExpressMailIntlRequest / EMCAAccount	optional	For future use. USPS Corporate Account		minOccurs=0
eVSExpressMailIntlRequest / HoldForManifest	optional	Restricted use. Holds manifest record for possible inclusion in SCAN request.	string	enumeration=Y enumeration=N
eVSExpressMailIntlRequest / EELPFC	optional repeating up to 1 times	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: <EELPFC>30.37a</EELPFC>	string	minOccurs=0 maxOccurs=1
eVSExpressMailIntlRequest / PriceOptions	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/.	string	default=COMMERCIAL BASE enumeration=COMMERCIAL PLUS enumeration=COMMERCIAL BASE enumeration=RETAIL
eVSExpressMailIntlRequest / Size	Required if	<Size> tag and any values within the <Size> tag should not result in an error response	string	minOccurs=0 maxOccurs=1
eVSExpressMailIntlRequest / Length	Required if	Value must be numeric. Units are inches. Required IF any dimension > 0	string	minOccurs=0 totalDigits=10
eVSExpressMailIntlRequest / Width	Required if	Value must be numeric. Units are inches. Required IF any dimension > 0	string	minOccurs=0 totalDigits=10
eVSExpressMailIntlRequest / Height	Required if	Value must be numeric. Units are inches.	string	minOccurs=0 totalDigits=10
eVSExpressMailIntlRequest / Girth	Required if	Value must be numeric. Units are inches. Required IF any dimension > 0	string	minOccurs=0 totalDigits=10
eVSExpressMailIntlRequest / LabelTime	optional	Available if Revision tag >= 2. LabelTime is used in conjunction with LabelDate to determine the Guarantee	string	Format hh:mm
eVSExpressMailIntlRequest / MeterPaymentFlag	optional	Set to Y if the Scheduled Delivery Date should appear on the label, N otherwise.	string	Default Y Enumerations: N Y
eVSExpressMailIntlRequest / ActionCode	optional	Passed to SPE file via the shipment manifest.	string	Default = M0 Enumeration=“M0” Enumeration=“S0” Enumeration=“ ”
eVSExpressMailIntlRequest / OptOutOfSPE	optional	Allows a customer to opt out of SPE file creation. “false” WILL create a SPE file.	boolean	Default = True Enumeration=true Enumeration=false
eVSExpressMailIntlRequest / PermitNumber	optional	Number associated with a mailing permit. The permit is permission to use a certain postage payment method for bulk and commercial mailings	string	minOccurs=0
eVSExpressMailIntlRequest / ImportersReferenceType	optional	Tax code / VAT no. / Importer Code. Example: ‘1’ = Tax Code ‘2’ = VAT no. ‘3’ = Importer Code ‘ ‘ = Space	string	minOccurs=0
eVSExpressMailIntlRequest / ImportersTelephoneNumber	optional	For Importer: 10 digits (including area code), with no punctuation. Use format: 2125551234 For example: <FromPhone>5555555555</FromPhone>	string	whiteSpace=collapse length=10 pattern=\d{10}
eVSExpressMailIntlRequest / ImportersFaxNumber	optional	For Importer: No format checking is done on international fax numbers. For example: <ToFax>011 52 (322) 222-0074</ToFax>	string	maxLength=30
eVSExpressMailIntlRequest / ImportersEmail	optional	For Importer: Complete valid e-mail address is required if tag is used. For example: <ToEmail>cpapple@email.com</ToEmail>	string	maxLength=30 whiteSpace=collapse pattern=([\w\-\.]+)@(([\w-]+\.)+)[a-zA-Z]{2,4}
eVSExpressMailIntlRequest / Machinable	optional	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. For example: <Machinable>false</Machinable>	boolean	default=true whiteSpace=collapse
eVSExpressMailIntlRequest / DestinationRateIndicator	required	Required for destination entry packagesenter either “I” or “N”. I= International Service Center (ISC) N = None	string	enumerations= I N
eVSExpressMailIntlRequest / MID	optional	Mailer Identifier - (MID), Represents a specific Mail Owner - 6 or 9 digit numbers used within the barcode to help manage ownership of a mail piece.	string	minOccurs=0
eVSExpressMailIntlRequest / LogisticsManagerMID	optional	Mailer Identifier of the Logistics Manager	string	minOccurs=0
eVSExpressMailIntlRequest / CRID	optional	Customer Registration IDentifier (CRID), Represents a specific Mail Owner: A unique ID for a company name and location combination.	string	minOccurs=0
eVSExpressMailIntlRequest / VendorCode	optional	The 4-digit code assigned to the vendor	string	minOccurs=0 Default=8300
eVSExpressMailIntlRequest / VendorProductVersionNumber	optional	Shipping/manifesting software’s product version number.	string	minOccurs=0
eVSExpressMailIntlRequest / ePostageMailerReporting	optional	Verifies Sender Information, sender fields must match From information when <ePostageMailerReporting>=1	string	Enumerations= 1 - (ePostage sender information in SSF ) 2 - (ePostage sender information through DES) 3 - (ePostage sender information using child MID)
eVSExpressMailIntlRequest / SenderFirstName	optional	First Name of Sender. For example: <SenderFirstName>Adam </ SenderFirstName> Required when <ePostageMailerReporting>=1	string	minLength=0, maxLength=49
eVSExpressMailIntlRequest / SenderLastName	optional	Last Name of Sender. For example: <SenderLastName>Smith </ SenderLastName> Required when <ePostageMailerReporting>=1	string	minLength=0, maxLength=75
eVSExpressMailIntlRequest / SenderBusinessName	optional	Values for Sender Business Name must be sent. For example: <SenderBusinessName>USPS</ SenderBusinessName>	string	minLength=0, maxLength=100
eVSExpressMailIntlRequest / SenderAddress1	optional	Sender address line. Use this tag for full address (Address1 and Address2) Must match Address1 and Address2 or will produce an error. For example: <SenderAddress1>STE 150 10 Elm Street </ SenderAddress1> Required when <ePostageMailerReporting>=1	string	minLength=0, maxLength=148
eVSExpressMailIntlRequest / SenderCity	optional	Sender city. For example: <SenderCity>BETHESDA</ SenderCity> Required when <ePostageMailerReporting>=1	string	minLength=0, maxLength=50
eVSExpressMailIntlRequest / SenderState	optional	Sender state. For example: <SenderState>MD</ SenderState> Required when <ePostageMailerReporting>=1	string	minLength=0, maxLength=2
eVSExpressMailIntlRequest / SenderZip5	optional	Sender ZIP code. For example: <SenderZip5>20212</SenderZip5> Required when <ePostageMailerReporting>=1	string	minLength=0, pattern=d(5)
eVSExpressMailIntlRequest / SenderPhone	optional	Sender Phone #. 10 digits required (including area code), with no punctuation. For example: <SenderPhone>2125551234</ SenderPhone> Required when <ePostageMailerReporting>=1	string	minLength=0, pattern=d(10)
eVSExpressMailIntlRequest / SenderEmail	optional	E-mail Address of Sender. Valid e-mail addresses must be used. For example: <SenderEMail>cpapple@email.com</ SenderEMail> Required when <ePostageMailerReporting>=1	string	minLength=0, pattern=([\w\-\.]+)@(([\w-]+\.)+)[a-zA-Z]{2,4}
eVSExpressMailIntlRequest / VERSION	optional		NMTOKEN	pattern value="\d+\.\d+"/>
eVSExpressMailIntlCertifyRequest	required	API=eVSExpressMailIntlCertify "Certify" signature is for testing and demonstration - does not produce a label that can be mailed.	(alias)

2.3.1 Sample Requests

All requests should hit the https://secure.shippingapis.com/ShippingAPI.dll end point with the API=eVSExpressMailIntl or eVSExpressMailIntlCertify and XML=<the sample XML request below> key value pairs using either a HTTP POST or a HTTP GET.

Request:

<eVSExpressMailIntlCertifyRequest USERID="XXXXXXXXXXXX"

<FromAddress2>7 North Wilke-Barre Blvd</FromAddress2>

<FromCity>Wilkes-Barre</FromCity>

<ToLastName>Apple</ToLastName>

<ToAddress1> Apartado 3068</ToAddress1>

<ToCity>Golden Rock</ToCity>

<ToCountry>Australia</ToCountry>

<ToEmail>cpapple@email.com</ToEmail>

<NonDeliveryOption>RETURN</NonDeliveryOption>

<RedirectZIPCode>MEXICO</RedirectZIPCode>

<Container>VARIABLE</Container>

<Description>Policy guidelines document</Description>

<CountryOfOrigin>United States</CountryOfOrigin>

</ItemDetail>

</ShippingContents>

<ContentType>DOCUMENTS</ContentType>

</eVSExpressMailIntlCertifyRequest>

2.4 Response Descriptions

Tag Name	Occurs	Description	Type	Validation
eVSExpressMailIntlResponse	required		(group)
eVSExpressMailIntlResponse/ Postage	required	Postage amount	decimal
eVSExpressMailIntlResponse/ TotalValue	required	Value of all items being shipped	decimal
eVSExpressMailIntlResponse/ SDRValue	required	Special Drawing Right calculated on Insured Amount	decimal
eVSExpressMailIntlResponse/ BarcodeNumber	required	Mail service related barcode.	string
eVSExpressMailIntlResponse/ LabelImage	required	Encoded images of label (may be empty depending upon layout option selected)	string
eVSExpressMailIntlResponse/ Page2Image	required	Encoded images of label (may be empty depending upon layout option selected)	string
eVSExpressMailIntlResponse/ Page3Image	required	Encoded images of label (may be empty depending upon layout option selected)	string
eVSExpressMailIntlResponse/ Page4Image	required	Encoded images of label (may be empty depending upon layout option selected)	string
eVSExpressMailIntlResponse/ Page5Image	required	Encoded images of label (may be empty depending upon layout option selected)	string
eVSExpressMailIntlResponse/ Page6Image	required	Encoded images of label (may be empty depending upon layout option selected)	string
eVSExpressMailIntlResponse/ Prohibitions	required	List of items prohibited from mailing based on country of destination	string
eVSExpressMailIntlResponse/ Restrictions	required	Restrictions on items being shipped based on country of destination	string
eVSExpressMailIntlResponse/ Observations	required	Additional mailing information based on country of destination	string
eVSExpressMailIntlResponse/ Regulations	required	Additional regulations for shipping to destination country	string
eVSExpressMailIntlResponse/ AdditionalRestrictions	required	Additional restrictions on items being shipped to destination country	string
eVSExpressMailIntlResponse/ InsuranceFee	optional	Insurance Fee	decimal	minExclusive=0.0 maxInclusive=5000
eVSExpressMailIntlResponse/ DestinationBarcodeNumber	optional	Appears if mail class is available.	String	minoccurs=0
eVSExpressMailIntlResponse/ GuaranteeAvailability	optional	Appears if ToPostalCode and LabelTime are available. The value will be the GuaranteeDate or a message.	string	If an estimated scheduled delivery date is available, the format will be MM/DD/YYYY e.g, 03/15/2015 If an estimated scheduled delivery date is not available, the format will be a string, e.g., 3 - 5 business days to many major markets
eVSExpressMailIntlResponse/ RemainingBarcodes	Required	This contains the number of remaining barcodes that can be generated for this particular request.	string
eVSExpressMailIntlResponse/ Warning	optional		string
eVSExpressMailIntlResponse	required		(alias)

2.4.1 Sample Response

Response:

<?xml version="1.0"?>

<LabelImage>.....removed.....</LabelImage>

<Page2Image>.....removed.....</Page2Image>

<Page3Image>.....removed.....</Page3Image>

<Page4Image>.....removed.....</Page4Image>

<Page5Image>.....removed.....</Page5Image>

Coins; bank notes; currency notes (paper money); securities of any kind payable to bearer; traveler's checks; platinum, gold, and silver (except for jewelry items meeting the requirement in "Restrictions" below); precious stones (except when contained in jewelry items meeting the requirement in "Restrictions" below); and other valuable articles are prohibited.

Fruit cartons (used or new).

Goods bearing the name "Anzac."

Goods produced wholly or partly in prisons or by convict labor.

Most food, plant, and animal products, including the use of products such as straw and other plant material as packing materials.

Perishable infectious biological substances.

Radioactive materials.

Registered philatelic articles with fictitious addresses.

Seditious literature.

Silencers for firearms.

Used bedding.

</Prohibitions>

Jewelry is permitted only when sent as an insured parcel using Priority Mail International service. In addition, Australian Customs regulations prohibit importation of jewelry that is made with ivory or from endangered species, such as snake, elephant, or crocodile, that does not have an accompanying Import/Export Permit in relation to the Convention on International Trade in Endangered Species of Wild Fauna and Flora (CITES).

Meat and other animal products; powdered or concentrated milk; and other dairy products requires permission to import from the Australian quarantine authorities.

Permission of the Australian Director-General of Health is required to import medicines.

</Restrictions>

<Observations>Duty may be levied on catalogs, price lists, circulars, and all advertising introduced into Australia through the mail, regardless of the class of mail used.</Observations>

Country Code:

Reciprocal Service Name:

Express Post

Required Customs Form/Endorsement

1. Business and commercial papers.

No form required. Endorse item clearly next to mailing label as BUSINESS PAPERS.

2. Merchandise samples without commercial value microfilm, microfiche, and computer data.

PS Form 2976-A, Customs Declaration and Dispatch Note CP 72, inside a PS Form 2976-E, Customs Declaration Envelope CP 91.

3. Merchandise and all articles subject to customs duty.

PS Form 2976-A, Customs Declaration and Dispatch Note CP 72, inside a PS Form 2976-E, Customs Declaration Envelope CP 91.

Note:

1. Coins; banknotes; currency notes, including paper money; securities of any kind payable to bearer; traveler's checks; platinum, gold, and silver; precious stones; jewelry; watches; and other valuable articles are prohibited in Priority Mail Express International shipments to Australia.

2. Priority Mail Express International With Guarantee service - which offers a date-certain, postage-refund guarantee - is available to Australia.

Areas Served:

All except Lord Howe Island and the Australian Antarctic territories.

</Regulations>

<AdditionalRestrictions>No Additional Restrictions Data found.</AdditionalRestrictions>

</eVSExpressMailIntlResponse>

2.5 eVS International Label Example – Express Mail International

2.6 Error Responses

Error conditions are handled at the main XML document level and Package node level. When parsing, it is best to check for an error document first before checking for good data. Error documents have the following format:

<Error>

<Number></Number>

<Source></Source>

<Description></Description>

<HelpFile></HelpFile>

<HelpContext></HelpContext>

</Error>

Where:

· Number = the error number generated by the Web Tools server.

· Source = the component and interface that generated the error on the Web Tools server.

· Description = the error description.

· HelpFile = [reserved for future use].

· HelpContext = [reserved for future use].

An <Error> element may be returned at the top (response) level if there is a problem with the syntax of the request, or if a system error occurs.

If you need assistance with an error response, contact the Internet Customer Care Center https://Emailus.usps.com/.

3.0 eVS Priority Mail International Label API

3.1 Overview

The eVS Priority Mail Express International Label API lets customers generate eVS Priority Mail Express International labels given the weight and dimensions of the item.

3.2 API Signature

*Scheme*	*Host*	*Path*	*API*	*XML*
https://	secure.shippingapis.com	/ShippingAPI.dll?	API=eVSPriorityMailIntl	&XML=(see Tag Descriptions below)
https://	secure.shippingapis.com	/ShippingAPI.dll?	API=eVSPriorityMailIntlCertify	&XML=(see Tag Descriptions below)

Note: The “eVSPriorityMailIntlCertify” API signature is for testing purposes and will not generate usable labels and barcodes.

3.3 Request Descriptions

Tag Name	Occurs	Description	Type	Validation
eVSPriorityMailIntlRequest	required	Produces a Priority Mail International label with customs declaration	(group)
eVSPriorityMailIntRequest / USERID	required	This attribute specifies your Web Tools ID. See the Developer's Guide for information on obtaining your USERID.	NMTOKEN
eVSPriorityMailIntRequest / PASSWORD	optional	For backward compatibility; not validated.	string
eVSPriorityMailIntRequest / APPID	optional		NMTOKEN
eVSPriorityMailIntlRequest / Option	optional	For future use.	empty
eVSPriorityMailIntlRequest / Revision	required	Use of value 2 required as of January 2011. For example: <Revision>2</Revision>	string
eVSPriorityMailIntlRequest / ImageParameters	optional	Groups alternate image options.	(group)	minoccurs=0
eVSPriorityMailIntlRequest / ImageParameters / ImageParameter	Optional, repeating up to 3 times	Returns alternate label image. Only alternate 4’’x6’’ size label image may be requested at this time. · 4X6LABEL (4X6 on a full page 8.5/11” background) · 4X6LABELL (Landscape – true size 4X6; image rotated, not on an 8.5 x 11 background page) · 4X6LABELP (Portrait – true size 4X6, not on an 8.5 x 11 background page) For example: <ImageParameter>4X6LABEL</ImageParameter>	string	minoccurs=0 maxoccurs=3 Enumerations= 4X6LABEL 4X6LABELL 4X6LABELP
eVSPriorityMailIntlRequest / FromFirstName	optional	Both FromFirstName and FromLastName are required if FromFirmName is left blank. Maximum Length: 32 characters total for First, Middle, and Last Names with space after first and middle name. For example: <FromFirstName>John</FromFirstName>	string	maxLength=30 minLength=1
eVSPriorityMailIntlRequest / FromMiddleInitial	optional	Middle Initial. Maximum Length: 32 characters total for First, Middle, and Last Names with space after first and middle name. For example: <FromMiddleInitial>L</FromMiddleInitial>	string	maxLength=1
eVSPriorityMailIntlRequest / FromLastName	optional	Both FromFirstName and FromLastName are required if FromFirmName is left blank. Maximum Length: 32 characters total for First, Middle, and Last Names with space after first and middle name. For example: <FromLastName>Doe</FromLastName>	string	maxLength=30 minLength=1
eVSPriorityMailIntlRequest / FromFirm	optional	FromFirm is required if FromFirstName and FromLastName are left blank. For example: <FromFirm>XYZ</FromFirm>	string	maxLength=32
eVSPriorityMailIntlRequest / FromAddress1	optional	Use this tag for a suite or apartment number only. Either Address1 or Address2 is required. For example: <FromAddress1>Suite 100</FromAddress1>	string	maxLength=32
eVSPriorityMailIntlRequest / FromAddress2	required	Use this tag for the primary address line. For example: <FromAddress2>10 Elm Street </FromAddress2>	string	maxLength=32 minLength=1 whiteSpace=collapse
eVSPriorityMailIntlRequest / FromUrbanization	optional	Use this tag for Puerto Rico only. ZIP Code prefixes 006 to 009, if area is so designated. For example: <FromUrbanization>URB Caparra Ter</FromUrbanization>	string	maxLength=32
eVSPriorityMailIntlRequest / FromCity	required	For example: <FromCity>Anytown</FromCity>	string	maxLength=16 minLength=1
eVSPriorityMailIntlRequest / FromState	required	Use 2-letter USPS abbreviation. For example: <FromState>ST</FromState>	string	length=2
eVSPriorityMailIntlRequest / FromZip5	required	Input tag exactly as presented, not all caps. 5 digits required. For example: <FromZip5>01234</FromZip5>	string	whiteSpace=collapse length=5 pattern=\d{5}
eVSPriorityMailIntlRequest / FromZip4	optional	Input tag exactly as presented, not all caps. If value is entered, 4 digits required. This is the ZIP+4 extension. For example: <FromZip4>5678</FromZip4>	string	whiteSpace=collapse length=4 pattern=\d{4}
eVSPriorityMailIntlRequest / FromPhone	required	10 digits required (including area code), with no punctuation. Use format: 2125551234 For example: <FromPhone>5555555555</FromPhone>	string	whiteSpace=collapse length=10 pattern=\d{10}
eVSPriorityMailIntlRequest / FromCustomsReference	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: <FromCustomsReference></FromCustomsReference>	string	maxLength=30
eVSPriorityMailIntlRequest / ToName	optional	Deprecated. See “ToFirstName” and “ToLastName” tags.	string	maxLength=36
eVSPriorityMailIntlRequest / ToFirstName	optional	Both ToFirstName and ToLastName are required if ToFirm is left blank. For example: <ToFirstName>John</ToFirstName>	string	maxLength=30
eVSPriorityMailIntlRequest / ToLastName	optional	Both ToFirstName and ToLastName are required if ToFirm is left blank. For example: <ToLastName>Doe</ToLastName>	string	maxLength=30
eVSPriorityMailIntlRequest / ToFirm	optional	ToFirm is required if ToFirstName and ToLastName are left blank. For example: <ToFirm>YYZ</ToFirm>	string	maxLength=36
eVSPriorityMailIntlRequest / ToAddress1	required	Three address lines are provided, but only 1 is required. Use as many as needed for complete address. For example: <ToAddress1> Apartado 3068</ToAddress1>	string	maxLength=36 minLength=1
eVSPriorityMailIntlRequest / ToAddress2	optional	Three address lines are provided, but only 1 is required. Use as many as needed for complete address. For example: <ToAddress2></ToAddress2>	string	maxLength=36
eVSPriorityMailIntlRequest / ToAddress3	optional	Three address lines are provided, but only 1 is required. Use as many as needed for complete address. For example: <ToAddress3></ToAddress3>	string	maxLength=36
eVSPriorityMailIntlRequest / ToCity	required	Recipient's city. For example: <ToCity>PUERTO VALLARTA</ToCity>	string	maxLength=18 minLength=1
eVSPriorityMailIntlRequest / ToProvince	optional	Enter the province for the recipient. For example: <ToProvince>JALISCO</ToProvince>	string	maxLength=9
eVSPriorityMailIntlRequest / ToCountry	required	The country name entered must match an entry from the USPS-approved International Index of Countries and 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. For example: <ToCountry>MEXICO</ToCountry>	string	minLength=1
eVSPriorityMailIntlRequest / ToPostalCode	required	Enter the postal code for the recipient. For example: <ToPostalCode>46807</ToPostalCode>	string	maxLength=9
eVSPriorityMailIntlRequest / ToPOBoxFlag	required	Indicates whether or not the To Address is a Post Office Box. For example: <ToPOBoxFlag>N</ToPOBoxFlag>	string	enumeration=Y enumeration=N
eVSPriorityMailIntlRequest / ToPhone	optional	No format checking is done on international phone numbers. Required when <ToPOBoxFlag>Y</ToPOBoxFlag> For example: <ToPhone>011 52 (322) 222-0069</ToPhone>	string	maxLength=30
eVSPriorityMailIntlRequest / ToFax	optional	No format checking is done on international fax numbers. For example: <ToFax>011 52 (322) 222-0074</ToFax>	string	maxLength=30
eVSPriorityMailIntlRequest / ToEmail	optional	Complete valid e-mail address is required if tag is used. For example: <ToEmail>cpapple@email.com</ToEmail>	string	maxLength=30 whiteSpace=collapse pattern=([\w\-\.]+)@(([\w-]+\.))+[a-zA-Z]{2,4}
eVSPriorityMailIntlRequest / ImportersReferenceNumber	optional	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: < ImportersReferenceNumber >Order 23432</ ImportersReferenceNumber >	string	maxLength=28
eVSPriorityMailIntlRequest / NonDeliveryOption	optional	In case package is undeliverable, enter one of the following: "RETURN" for package to be returned to <FromAddress> above. "REDIRECT" to return package to address specified below in <AltReturn…> tags. "ABANDON" to dispose of undeliverable package. For example: <NonDeliveryOption>RETURN</NonDeliveryOption>	string	default=ABANDON enumeration=RETURN enumeration=REDIRECT enumeration=ABANDON
eVSPriorityMailIntlRequest / RedirectName	Optional		String	Minoccurs=0
eVSPriorityMailIntlRequest / RedirectName	optional	Enter a value for the recipient's name.	string	minOccurs=0
eVSPriorityMailIntlRequest / RedirectEmail	optional	Complete valid e-mail address is required if tag is used.	string	minOccurs=0
eVSPriorityMailIntlRequest / RedirectSMS	optional	This value must be a syntactically-valid SMS number.	string	minOccurs=0
eVSPriorityMailIntlRequest / RedirectAddress	optional	Enter the redirect address. This is a free form field.	string	minOccurs=0 maxLength=48
eVSPriorityMailIntlRequest / RedirectCity	optional	Redirect city. For example: <T RedirectCity >ANYTOWN</ RedirectCity >	string	minLength=0 maxLength=21
eVSPriorityMailIntlRequest / RedirectState	optional	Redirect state. For example: < RedirectState >MN</ RedirectState>	string	minLength=0 pattern=\w{2}
eVSPriorityMailIntlRequest / RedirectZipCode	optional	Redirect ZIP code. For example: < RedirectZipCode >12345</ RedirectZipCode>	string	minLength=0 pattern=\d{5}
eVSPriorityMailIntlRequest / RedirectZip4	Optional	Redirect ZIP+4 extension. For example: <ToZip5>01234</ToZip5>	string	minLength=0
eVSPriorityMailIntlRequest / Container	optional	Use <Container>MDFLATRATEBOX</Container> or <Container>LGFLATRATEBOX</Container> or <Container>SMFLATRATEBOX</Container> or <Container>LGVIDEOBOX</Container> or <Container>DVDBOX</Container> for flat rate boxes, <Container>FLATRATEENV</Container> or <Container>LEGALFLATRATEENV</Container> or <Container>PADDEDFLATRATEENV</Container> or <Container>WINDOWFLATRATEENV</Container> or <Container>SMFLATRATEENV</Container> or <Container>GIFTCARDFLATRATEENV</Container> for flat rate envelopes. Otherwise, use to specify special containers or container attributes that may affect postage.	string	default=VARIABLE enumerations= · VARIABLE · LGFLATRATEBOX · SMFLATRATEBOX · MDFLATRATEBOX · FLATRATEENV · LEGALFLATRATEENV · PADDEDFLATRATEENV · SMFLATRATEENV · WINDOWFLATRATEENV · GIFTCARDFLATRATEENV · LGVIDEOBOX · FLATRATEENV
eVSPriorityMailIntlRequest / ShippingContents	required		(group)
eVSPriorityMailIntlRequest / ShippingContents / ItemDetail	required repeating up to 30 times	Groups individual item details	(group)
eVSPriorityMailIntlRequest / ShippingContents / ItemDetail / Description	required	Description of the item. For example: <Description>Policy guidelines document</Description>	string	maxLength=30 minLength=1 whiteSpace=collapse
eVSPriorityMailIntlRequest / ShippingContents / ItemDetail / Quantity	required	Quantity of the item. Integer value required. For example: <Quantity>1</Quantity>	integer	whiteSpace=collapse minExclusive=0
eVSPriorityMailIntlRequest / ShippingContents / ItemDetail / Value	required	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. For example: <Value>55.00</Value>	decimal	whiteSpace=collapse minExclusive=0
eVSPriorityMailIntlRequest / ShippingContents / ItemDetail / NetPounds	required	Provide the pounds component of the weight of the individual item listed with <Description>. For example: <NetPounds>1</NetPounds>	integer	default=0 whiteSpace=collapse
eVSPriorityMailIntlRequest / ShippingContents / ItemDetail / NetOunces	required	Provide the ounces component of the weight of the individual item listed with <Description>. For example: <NetOunces>5</NetOunces>	decimal	default=0.0 whiteSpace=collapse
eVSPriorityMailIntlRequest / ShippingContents / ItemDetail / HSTariffNumber	required	For commercial items only. If known, the HS tariff number must be based on the Harmonized Commodity Description and Coding System developed by the World Customs Organization. For example: <HSTariffNumber>490110</HSTariffNumber>	String	whiteSpace=collapse maxLength=12 pattern=\d{0,12}
eVSPriorityMailIntlRequest / ShippingContents / ItemDetail / CountryOfOrigin	required	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 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. See Appendix A for Abbrevations. For example: <CountryOfOrigin>United States</Co