eVS International Label API

 

 

USPS Web Tools™

Application Programming Interface

User Guide

Version 3.4 (02/19/2021)

 

 

 

 

 

 

United States Postal Service Logo
 

 

 

 

 


Table of Contents

1.0    Introduction to Web Tools. 4

1.1            Before you get started: 4

2.0    eVS Priority Mail Express International Label API 5

2.1            Overview. 5

2.1.1      API Signature. 5

2.2            Request Descriptions. 5

2.2.1      Sample Request 18

2.3            Response Descriptions. 19

2.3.1      Sample Response. 21

3.0    eVS Priority Mail International Label API 22

3.1            Overview. 22

3.1.1      API Signature. 22

3.2            Request Descriptions. 23

3.2.1      Sample Request 36

3.3            Response Descriptions. 38

3.3.1      Sample Response. 40

4.0    eVS First Class Mail International Label API 42

4.1            Overview. 42

4.1.1      API Signature. 43

4.2            Request Descriptions. 43

4.2.1      Sample Request 55

4.3            Response Descriptions. 56

4.3.1      Sample Response. 57

5.0    eVS GXG Get Label API 59

5.1            Overview. 59

5.1.1      API Signature. 59

5.2            Request Descriptions. 59

5.2.1      Sample Request 70

5.3            Response Descriptions. 72

5.3.1      Sample Response. 73

6.0    eVS International Cancel API 74

6.1            Overview. 74

6.1.1      API Signature. 74

6.2            Request Descriptions. 74

6.2.1      Sample Request 74

6.3            Response Descriptions. 74

6.3.1      Sample Response. 75

7.0    Appendix A. 76

7.1            eVS International Label Example – Express Mail International 76

7.2            eVS International Label Example – Priority Mail International 77

7.3            eVS International Label Example – First Class Mail International 78

7.4            eVS International Label Example – GXG Get Label 79

8.0    Appendix B. 80

8.1            Country Codes. 80

 


 

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 Developers 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 troubleshooting.

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 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:

<Pounds>2</Pounds>

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

1.1         Before you get started:

The only option for creating labels through our APIs requires eVS setup/enrollment. In general, eVS:

·        Requires 50 pieces or 50 pounds per mailing

·        Requires a permit imprint

·        Requires payment via ACH debit daily (no other forms of payment)

·        Handles origin entered mail (no destination entry or presort)

·        Requires enrollment and new Mailer IDs (MIDs) and permits

·        Supports domestic/international/APO/FPO/DPO/PTFAS locations

eVS, or Electronic Verification System, allows high-volume package mailers and package consolidators to document and pay postage, including special service fees, using electronic manifest files. The files are transmitted over the Internet to a Postal Service™ database. eVS is designed to make it easy for high-volume package mailers to take advantage of destination entry rates.

If you want to explore using eVS, please first contact the eVS@usps.gov.

For registration please visit: https://www.usps.com/postalone/evs.htm. If that will not work for you, then you can follow up with sales@usps.gov (or your local Postmaster or USPS Sales Manager) for additional solutions outside of the Web Tools API suite.

Note: The “Certify” API signatures are for testing purposes and will not generate usable labels and barcodes.

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:

·        A master Mailer ID is created

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

·        A permit number is created

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

·        A CAPS Debit account is created for payment processing

o   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 Web Tools Technical Documentation Page.

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 and integrated customs forms.

 

Note: Scan form is eligible for eVS if HoldForManifest is set to ‘Y’ (Yes).

 

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

2.1.1   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)

2.2         Request Descriptions

Tag Name

Occurs

Description

Type

Validation

eVSExpressMailIntlRequest

Required

 

(Alias)

 

eVSExpressMailIntlRequest / USERID

Required

This attribute specifies your WebTools ID. See the Developers Guide for information on obtaining your USERID.

For example:

<USERID=”XXXXXXXXXX”>

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)

·        4X6ZPL203DPI - (ZPL - Zebra Programming Language) format. When using this enumeration, <ImageType> is required - this tag cannot be left blank. Integrators should use either “TIF” or “PDF” for ZPL – neither value will impact the label image itself, but it must be included in the request to return a successful response.

·        4X6ZPL300DPI - Prints a label formatted for ZPL printers in 300 dpi. When using this enumeration, <ImageType> is required - this tag cannot be left blank. Integrators should use either “TIF” or “PDF” for ZPL – neither value will impact the label image itself, but it must be included in the request to return a successful response.

For example: <ImageParameter>4X6LABEL</ImageParameter>

String

Enumerations=

·        4X6LABEL

·        4X6LABELL

·        4X6LABELP

·        4X6ZPL203DPI

·        4X6ZPL300DPI

eVSExpressMailIntlRequest / FromFirstName

Required

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

Required

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

Required

FromFirm is Required if FromFirstName and FromLastName are left blank.

For example: <FromFirm>ABC Corp</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>Suite 101 </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>Bristol</FromCity>

String

maxLength=16
minLength=1

eVSExpressMailIntlRequest / FromState

Required

Use 2-letter USPS state abbreviation.

For example: <FromState>CT</FromState>

String

length=2

eVSExpressMailIntlRequest / FromZip5

Required

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

For example: <FromZip5>06010</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

Required

Both ToFirstName and ToLastName are Required if ToFirm is left blank.

For example: <ToFirstName>John</ToFirstName

String

maxLength=30

eVSExpressMailIntlRequest / ToLastName

Required

Both ToFirstName and ToLastName are Required if ToFirm is left blank.

For example: <ToLastName>Doe</ToLastName

String

maxLength=30

eVSExpressMailIntlRequest / ToFirm

Required

ToFirm is Required if ToFirstName and ToLastName are left blank.

For example: <ToFirm>ABC Co</ToFirm

String

maxLength=36

eVSExpressMailIntlRequest / ToAddress1

Optional

Three address lines are provided, but only 1 is Required. Use as many as needed for complete address.

For example: <ToAddress1> 60 Carlton St</ToAddress1>

String

maxLength=36
minLength=1

eVSExpressMailIntlRequest / ToAddress2

Required

Three address lines are provided, but only 1 is Required. Use as many as needed for complete address.

String

maxLength=36

eVSExpressMailIntlRequest / ToAddress3

Optional

Three address lines are provided, but only 1 is Required. Use as many as needed for complete address.

String

maxLength=36

eVSExpressMailIntlRequest / ToCity

Required

Recipient's city.

For example: <ToCity>Toronto</ToCity>

String

maxLength=18
minLength=1

eVSExpressMailIntlRequest / ToProvince

Optional

Enter the province for the recipient.

For example: <ToProvince>ON</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>Canada</ToCountry>

String

minLength=1

eVSExpressMailIntlRequest / ToPostalCode

Required

Enter the postal code for the recipient.

For example: <ToPostalCode> M5B 1J2</ToPostalCode>

String

maxLength=9

eVSExpressMailIntlRequest / ToPOBoxFlag

Required

Indicates whether the destination address is a Post Office Box.

For example: <ToPOBoxFlag>N</ToPOBoxFlag>

String

Enumerations=

·        Y

·        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

Enumerations=

·        RETURN

·        REDIRECT

·        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

Container type.

String

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.

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>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 : “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

Enumerations=

·        Y

·        N

eVSExpressMailIntlRequest / Comments

Optional

Enter any comments.

For example: <Comments> eVSExpressMailIntl</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

Label Image Type. Note: All <ImageType> values are ignored when <ImageParameter> = “4X6ZPL203DPI” or “4X6ZPL300DPI”.

For example: <ImageType>PDF</ImageType>

String

Enumerations=

·        PDF

·        TIF

·        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

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 Code of Post Office or collection box where item is mailed. May be different than FromZip5. This tag will take precedence over FromZip5 when provided. 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

Enumerations=

·        Y

·        N

eVSExpressMailIntlRequest / EELPFC

Optional repeating up to 1 time

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

Enumerations=

·        COMMERCIAL PLUS

·        COMMERCIAL BASE

eVSExpressMailIntlRequest / Length

Optional

Value must be numeric. Units are inches. If partial dimensions are provided, an error response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non-rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non-rectangular packages.  

 

For more details on dimensional weight pricing or dimension validation reference IMM https://pe.usps.com/text/imm/welcome.htm

String

minOccurs=0
totalDigits=10  

eVSExpressMailIntlRequest / Width

Optional

Value must be numeric. Units are inches. If partial dimensions are provided, an error response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non-rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non-rectangular packages.  

 

For more details on dimensional weight pricing or dimension validation reference IMM https://pe.usps.com/text/imm/welcome.htm

String

minOccurs=0
totalDigits=10  

eVSExpressMailIntlRequest / Height

Optional

Value must be numeric. Units are inches. If partial dimensions are provided, an error response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non-rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non-rectangular packages.  

 

For more details on dimensional weight pricing or dimension validation reference IMM https://pe.usps.com/text/imm/welcome.htm

String

minOccurs=0
totalDigits=10  

eVSExpressMailIntlRequest / Girth

Optional

Value must be numeric. Units are inches. If partial dimensions are provided, an error response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non-rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non-rectangular packages.  

 

For more details on dimensional weight pricing or dimension validation reference IMM https://pe.usps.com/text/imm/welcome.htm

String

minOccurs=0
totalDigits=10  

eVSExpressMailIntlRequest / LabelTime

Optional

Available if <Revision>= 2.

LabelTime is used in conjunction with LabelDate to determine the Guarantee

String

Format hh:mm

eVSExpressMailIntlRequest / MeterPaymentFlag

Optional

Meter payment indicator

String

Enumerations=

·        N

·        Y

eVSExpressMailIntlRequest / ActionCode

Optional

Used to specify the action code.Value is passed to Shipping Partner Event file via the shipment manifest.

·        M0 – Mailer Owner

·        S0 – Service Provider

For example: <ActionCode>M0</ActionCode>

String

Enumerations=

·        M0

·        S0

 

eVSExpressMailIntlRequest / OptOutOfSPE

Optional

Allows a customer to opt out of SPE file creation. “false” WILL create a SPE file. Note: This request tag is case sensitive.

Boolean

Enumerations=

·        true

·        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 / AccountZipCode

Optional

ZIP of Account Post Office where mailed if different from <FromZip5>. Written to Postal Manifest Detail record. Must be valid ZIP Code.

For example: <AccountZipCode>00962</AccountZipCode>  

String

whiteSpace=collapse
length=5
pattern=\d{5}  

eVSExpressMailIntlRequest / ImportersReferenceType

Optional

Tax code / VAT no. / Importer Code. 

 

String

minOccurs=0

Enumerations=

·        TAXCODE

·        VAT

·        IMPORTERCODE

eVSExpressMailIntlRequest / ImportersTelephoneNumber

Optional

For Importer: 10 digits (including area code), with no punctuation.

Use format: 2125551234

For example: <ImportersTelephoneNumber>5555555555</ImportersTelephoneNumber>

String

whiteSpace=collapse

length=10

pattern=\d{10}

eVSExpressMailIntlRequest / ImportersFaxNumber

Optional

For Importer: No format checking is done on international fax numbers.

For example: <ImportersFaxNumber>011 52 (322) 222-0074</ImportersFaxNumber>

String

maxLength=30

eVSExpressMailIntlRequest / ImportersEmail

Optional

For Importer: Complete valid e-mail address is Required if tag is used.

For example: <ImportersEmail>cpapple@email.com</ImportersEmail>

String

maxLength=30

whiteSpace=collapse

pattern=([\w\-\.]+)@(([\w-]+\.)+)[a-zA-Z]{2,4}

eVSExpressMailIntlRequest / Machinable

Optional

Indicates whether the item is machinable.

For example: <Machinable>false</Machinable> 

Boolean

default=true

whiteSpace=collapse  

eVSExpressMailIntlRequest / DestinationRateIndicator

Required

Required for destination entry packages enter either “I” or “N”.

·        I= International Service Center (ISC)

·        N = None

String

Enumerations=

·        I

·        N

eVSExpressMailIntlRequest / MID

Optional

Mailer ID (MID), Represents Mail Owner MID.

Located in position #13 in the Detail 1 record of the Shipping Services File v2.0.

For example: <MID>847654321</ MID>

String

Length=6 or 9 positions, if populated

eVSExpressMailIntlRequest / LogisticsManagerMID

Optional

The MID of the company that manages the mailing.

Located in position #12 in the Detail 1 record of the Shipping Services File v2.0.

Note: If LogisticsManagerMID is populated, either CRID or MID must also be populated.

For example: <LogisticsManagerMID>489001< / LogisticsManagerMID>

String

Length=6 or 9 positions, if populated

eVSExpressMailIntlRequest / CRID

Optional

Customer Registration ID, Represents Mail Owner CRID.

Located in position #20 in the Detail 1 record of the Shipping Services File v2.0.

For example: <CRID>544762</ CRID>

String

minLength=0
maxLength=15

eVSExpressMailIntlRequest / VendorCode

Optional

Code from vendor software to identify the developer of the shipping system.

Located in position #15 in the Detail 1 record of the Shipping Services File v2.0.

For example: <VendorCode>1234<VendorCode>

String

minLength=0
maxLength=4

default=8300

eVSExpressMailIntlRequest / VendorProductVersionNumber

Optional

Shipping software’s product version number.

Located in position #16 in the Detail 1 record of the Shipping Services File v2.0.

For example: <VendorProductVersionNumber>5.02.1B</  VendorProductVersionNumber>

String

minLength=0
maxLength=8

eVSExpressMailIntlRequest / ePostageMailerReporting

Optional

Verifies Sender Information, sender fields must match From information when <ePostageMailerReporting>=1

·        1 - (ePostage sender information in SSF)

·        2 - (ePostage sender information through DES)

·        3 - (ePostage sender information using child MID)

String

Enumerations=

·        1

·        2

·        3

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}

eVSExpressMailIntRequest

Required

 

(Alias)

 

2.2.1     Sample Request

Request: eVSExpressMailIntlRequest

<eVSExpressMailIntlRequest USERID="XXXXXXXXXXXX">

<Option></Option>

<Revision>2</Revision>

<ImageParameters>

<ImageParameter>4X6LABEL</ImageParameter>

</ImageParameters>

<FromFirstName>Joseph</FromFirstName>

<FromMiddleInitial>J</FromMiddleInitial>

<FromLastName>Jones</FromLastName>

<FromFirm>Postal Service</FromFirm>

<FromAddress1>Suite 101</FromAddress1>

<FromAddress2>901 D Street SW</FromAddress2>

<FromUrbanization/>

<FromCity>Washington</FromCity>

<FromState>DC</FromState>

<FromZip5>20024</FromZip5>

<FromZip4>6129</FromZip4>

<FromPhone>9198887652</FromPhone>

<FromCustomsReference>45655332</FromCustomsReference>

<ToFirstName>Jon</ToFirstName>

<ToLastName>John</ToLastName>

<ToFirm>Coffee Five</ToFirm>

<ToAddress1>R. da Quitanda, 86 - quiosque 01</ToAddress1>

<ToCity>Centro</ToCity>

<ToProvince>Rio de Janeiro</ToProvince>

<ToCountry>BRAZIL</ToCountry>

<ToPostalCode>20091-902</ToPostalCode>

<ToPOBoxFlag>N</ToPOBoxFlag>

<ToPhone>7771234567</ToPhone>

<ToFax>3012929999</ToFax>

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

<ImportersReferenceNumber>E382788</ImportersReferenceNumber>

<NonDeliveryOption>RETURN</NonDeliveryOption>

<Container>VARIABLE</Container>

<ShippingContents>

<ItemDetail>

<Description>Cleaning Manual</Description>

<Quantity>1</Quantity>

<Value>15</Value>

<NetPounds>0</NetPounds>

<NetOunces>10</NetOunces>

<HSTariffNumber>490110</HSTariffNumber>

<CountryOfOrigin>UNITED STATES</CountryOfOrigin>

</ItemDetail>

</ShippingContents>

<InsuredNumber>E789656</InsuredNumber>

<InsuredAmount>15</InsuredAmount>

<Postage>5</Postage>

<GrossPounds>0</GrossPounds>

<GrossOunces>10</GrossOunces>

<ContentType>MERCHANDISE</ContentType>

<Agreement>Y</Agreement>

<Comments>eVSExpressMailIntl</Comments>

<LicenseNumber>LIC-24356879</LicenseNumber>

<CertificateNumber>CERT-97865342</CertificateNumber>

<InvoiceNumber>INV-040903</InvoiceNumber>

<ImageType>PDF</ImageType>

<ImageLayout>ONEPERFILE</ImageLayout>

<CustomerRefNo>EF789UJK</CustomerRefNo>

<POZipCode/>

<LabelDate>10/10/20</LabelDate>

<HoldForManifest>N</HoldForManifest>

<Length>12</Length>

<Width>0.5</Width>

<Height>9</Height>

<Girth>0</Girth>

<LabelTime>06:57:37</LabelTime>

<MeterPaymentFlag>Y</MeterPaymentFlag>

<ActionCode>M0</ActionCode>

<OptOutOfSPE>false</OptOutOfSPE>

<ImportersReferenceType>TAXCODE</ImportersReferenceType>

<ImportersTelephoneNumber>8976667878</ImportersTelephoneNumber>

<ImportersEmail>nancy@email.com</ImportersEmail>

<Machinable>false</Machinable>

<DestinationRateIndicator>N</DestinationRateIndicator>

</eVSExpressMailIntlRequest>

2.3         Response Descriptions

Tag Name

Occurs

Description

Type

Validation

eVSExpressMailIntlResponse

Required

 

(Alias)

 

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. 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

String

 

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.3.1     Sample Response

Response:eVSExpressMailIntl

<eVSExpressMailIntlResponse>

<Postage>67.84</Postage>

<TotalValue>15.00</TotalValue>

<SDRValue>10.83</SDRValue>

<BarcodeNumber>EB321424860US</BarcodeNumber>

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

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

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

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

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

<Page6Image></Page6Image>

<Prohibitions> Banknotes; currency notes; paper money; securities payable to bearer; and traveler's checks. Coins; manufactured and unmanufactured platinum, gold, and silver; precious stones; jewels; expensive jewelry; and other valuable articles. Commercial samples that promote tobacco products or smoking-related merchandise. Commercial shipments that contain cigarettes, cigarillos, cigars, loose and packaged tobacco, pipes, and other smoking devices. Items that are fragile, either by nature or due to inadequate packing, that could cause harm to individuals or equipment. Medicines whose formulas are not listed in the official pharmacopeias or not licensed by the Brazilian Department of Public Health. Perishable infectious biological substances. Perishable noninfectious biological substances. Playing cards. Poniards, stilettos, poniard blades; canes, umbrellas, or any other articles containing swords, daggers, or guns; handcuffs, and blackjacks. Primary educational books not written in Portuguese. Radioactive materials. Regulation arms and munitions of Brazil and parts. Air guns. Reducing tubes and silencers for firearms. Salted or smoked meat, and other foodstuffs of animal origin. Seeds and seedlings of coffee, shrubs. Used consumer goods (See Observation #5 for exception).

</Prohibitions>

<Restrictions>

Medicines must be accompanied by a prescription from the attendant Brazilian doctor. This prescription should be on a chemist's form, bearing the name, private address or office of the doctor, his registration number with the Brazil National Medical Council and a Portuguese translation of the instructions, as necessary. Postal packages containing medicaments and not satisfying the above-mentioned conditions will be returned to the senders or, if abandoned, treated as undeliverable items. Postage stamps are admitted only in registered First-Class Package International Service with Registered Mail service shipments. Saccharine and other artificial sweeteners for artificial beverages require permission from the Brazilian Department of Public Health for importation.

</Restrictions>

<Observations>

1. Empresa Brasileira de Correios e Telégrafos (ECT) is introducing a "Fee for Postal Dispatch" with a current value of 15 Brazilian reals (BRL) for items presented to customs. If the addressee has not properly paid this fee, ECT will return the item to the sender. 2. Import licenses are required for many kinds of goods. ECT recommends that the sender ascertain from the addressee before mailing that the addressee holds the necessary documents. A shipment that does not have a required import permit is subject to confiscation as contraband. 3. The mailer must affix all necessary or relevant documents including invoices, export/import licenses, certificates of origin, health certificates, etc., to the outside of the item. 4. Imports are allowed by mail, including mail order catalog shipments, up to a value of U.S. $500 (U.S. $1,000 for computer software) without the requirement of an import license provided the item is not for resale. Shipments valued at no more than U.S. $50 are duty-free and are delivered to the addressee; shipments above U.S. $50 can be picked up at the post office upon payment of import duties. Imports that are prohibited or subject to special regulations must comply with applicable Brazilian government provisions. Identical shipments from the same source to the same person or address in Brazil within a 90-day period are considered part of the same shipment and may be subject to confiscation. Other merchandise that usually enters duty-free include items such as newspapers, maps, books, and magazines. 5. The mailer must fully and accurately complete the customs declarations, including the landline or mobile telephone number of the addressee, if available, and detailed information concerning the contents and value of the item, such as branded product description, model, serial number, and value of each individual article within the item. ECT immediately returns to the sender an item that does not have a properly completed customs declaration. 6. The importer tax identification (ID) number is required for all items containing goods. In Brazil, the importer tax ID number is known as "CPF" (format: 000.000.000-00) for natural persons and as "CNPJ" (format: 00.000.000/0000-00) for legal persons. This information must be provided either by the mailer in the importer reference field of the customs declaration form or on the commercial invoice, or by the importer through the Correios website at www2.correios.com.br/sistemas/rastreamento. 7. Shipments that do not indicate the applicable postage and fees on PS Form 2976-A will hinder the customs clearance process, causing delays to clear the items. 8. Used consumer goods may only be sent to charitable organizations that are recognized by the Brazilian government as being entities which serve the public interest.

</Observations>

<Regulations>

Country Code: BR Reciprocal Service Name; Serca Required Customs Form/Endorsement 1. Correspondence and business papers. PS Form 2976-B placed inside PS Form 2976-E (plastic envelope). Endorse item clearly next to mailing label as BUSINESS PAPERS. 2. Merchandise, merchandise samples without commercial value, documents, computer data, and all articles subject to customs duty. PS Form 2976-B placed inside PS Form 2976-E (plastic envelope). Include an invoice with all commercial shipments. Note: 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 Brazil. Areas Served: All

</Regulations>

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

<InsuranceFee>0</InsuranceFee>

<GuaranteeAvailability>3-5 business days to many major markets</GuaranteeAvailability>

<RemainingBarcodes>9773</RemainingBarcodes>

</eVSExpressMailIntlResponse>

 

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.

 

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

3.1.1       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)

3.2           Request Descriptions

Tag Name

Occurs

Description

Type

Validation

eVSPriorityMailIntRequest

Required

Produces a Priority Mail International label with customs declaration  

(Alias)

 

eVSPriorityMailIntRequest / USERID

Required

This attribute specifies your WebTools ID. See the Developers Guide for information on obtaining your USERID.

For example:

<USERID=”XXXXXXXXXX”>

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)

·        4X6ZPL203DPI - (ZPL - Zebra Programming Language) format. When using this enumeration, <ImageType> is required - this tag cannot be left blank. Integrators should use either “TIF” or “PDF” for ZPL – neither value will impact the label image itself, but it must be included in the request to return a successful response.

·        4X6ZPL300DPI - Prints a label formatted for ZPL printers in 300 dpi. When using this enumeration, <ImageType> is required - this tag cannot be left blank. Integrators should use either “TIF” or “PDF” for ZPL – neither value will impact the label image itself, but it must be included in the request to return a successful response.

For example: <ImageParameter>4X6LABEL</ImageParameter>

String

Enumerations=

·        4X6LABEL

·        4X6LABELL

·        4X6LABELP

·        4X6ZPL203DPI

·        4X6ZPL300DPI

eVSPriorityMailIntlRequest / FromFirstName

Required

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

Required

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

Required

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> 45655332 </FromCustomsReference>

String

maxLength=30  

eVSPriorityMailIntlRequest / ToName

Optional

Deprecated.  See “ToFirstName” and “ToLastName” tags. 

String

maxLength=36

eVSPriorityMailIntlRequest / ToFirstName

Required

Both ToFirstName and ToLastName are Required if ToFirm is left blank.

For example: <ToFirstName>John</ToFirstName>

String

maxLength=30

eVSPriorityMailIntlRequest / ToLastName

Required

Both ToFirstName and ToLastName are Required if ToFirm is left blank.

For example: <ToLastName>Doe</ToLastName

String

maxLength=30

eVSPriorityMailIntlRequest / ToFirm

Required

ToFirm is Required if ToFirstName and ToLastName are left blank.

For example: <ToFirm>YYZ</ToFirm

String

maxLength=36

eVSPriorityMailIntlRequest / ToAddress1

Optional

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

Required

Three address lines are provided, but only 1 is Required. Use as many as needed for complete address.

String

maxLength=36

eVSPriorityMailIntlRequest / ToAddress3

Optional

Three address lines are provided, but only 1 is Required. Use as many as needed for complete address.

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 the destination address is a Post Office Box.

For example: <ToPOBoxFlag>N</ToPOBoxFlag>  

String

Enumerations=

·        Y

·        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

Enumerations=

·        RETURN

·        REDIRECT

·        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: <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

For example: <Container>MDFLATRATEBOX</Container>

Otherwise, use to specify special containers or container attributes that may affect postage.

String

Enumerations=

·      VARIABLE

·        LGFLATRATEBOX

·        SMFLATRATEBOX

·        MDFLATRATEBOX

·        FLATRATEENV

·        LEGALFLATRATEENV

·        PADDEDFLATRATEENV

·        SMFLATRATEENV

·        WINDOWFLATRATEENV

·        GIFTCARDFLATRATEENV

·        LGVIDEOBOX

·        RECTANGULAR

·        FLATRATEENV

·        NONRECTANGULAR

                       

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.

For example: 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.

For example: <CountryOfOrigin>United States</CountryOfOrigin>  

String

 

eVSPriorityMailIntlRequest / Insured

Optional

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

Enumerations=

·        Y

·        N

eVSPriorityMailIntlRequest / InsuredNumber

Optional

For backward-compatibility; not validated.

String

 

eVSPriorityMailIntlRequest / InsuredAmount

Optional

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

For example: <InsuredAmount>100.00</InsuredAmount>

Decimal

length=0  

eVSPriorityMailIntlRequest / 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>  

Decimal

length=0  

eVSPriorityMailIntlRequest / 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.

WebTools 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  

eVSPriorityMailIntlRequest / GrossOunces

Required

Enter the ounces component of the total package weight with this tag.

For example: <GrossOunces>0</GrossOunces>  

Integer

whiteSpace=collapse  

eVSPriorityMailIntlRequest / ContentType

Required

Specifies the content of the package or envelope.

For example: <ContentType>DOCUMENTS</ContentType>

Note : “NonnegotiableDocument” and “Documents” both signify mailable non-negotiable documents and are insured automatically for up to $100. 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

·        NONNEGOTIABLEDOCUMENT

·        PHARMACUTICALS

·        MEDICALSUPPLIES

·        OTHER  

eVSPriorityMailIntlRequest / ContentTypeOther

Optional

Required when <ContentType>OTHER<ContentType>.  Maximum length enforced via truncation 

String

maxLength=15

whiteSpace=collapse  

eVSPriorityMailIntlRequest / 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

Enumerations=

·        Y

·        N  

eVSPriorityMailIntlRequest / Comments

Optional

Enter any comments.

For example: <Comments></Comments>

String

maxLength=76  

eVSPriorityMailIntlRequest / LicenseNumber

Optional

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

For example: <LicenseNumber>LIC-24356879</LicenseNumber>

String

maxLength=24  

eVSPriorityMailIntlRequest / CertificateNumber

Optional

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

For example: <CertificateNumber>CERT-97865342</CertificateNumber>

String

maxLength=24  

eVSPriorityMailIntlRequest / InvoiceNumber

Optional

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

For example: <InvoiceNumber>INV-040903</InvoiceNumber>

String

maxLength=24  

eVSPriorityMailIntlRequest / ImageType

Required

Label Image Type. Note: All <ImageType> values are ignored when <ImageParameter> = “4X6ZPL203DPI” or “4X6ZPL300DPI”.

For example: <ImageType>PDF</ImageType>

String

Enumerations=

·        PDF

·        TIF

·        NONE  

eVSPriorityMailIntlRequest / 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

Enumerations=

·        ONEPERFILE

·        ALLINONEFILE

·        TRIMONEPERFILE

·        TRIMALLINONEFILE  

eVSPriorityMailIntlRequest / CustomerRefNo

Optional

Written to Postal Manifest Detail record.

For example: <CustomerRefNo>Ref 369246</CustomerRefNo>

String

maxLength=30  

eVSPriorityMailIntlRequest / CustomerRefNo2

Optional

Written to Postal Manifest Detail record.

For example: <CustomerRefNo2>ACT369246</CustomerRefNo2>

String

maxLength=30  

eVSPriorityMailIntlRequest / POZipCode

Optional

ZIP Code of Post Office or collection box where item is mailed. May be different than FromZip5. This tag will take precedence over FromZip5 when provided. For example: <POZipCode>00962</POZipCode>  

String

whiteSpace=collapse

length=5

pattern=\d{5}  

eVSPriorityMailIntlRequest / 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)?  

eVSPriorityMailIntlRequest / HoldForManifest

Optional

Restricted use. Holds manifest record for possible inclusion in SCAN request.

String

Enumerations=

·        Y

·        N

eVSPriorityMailIntlRequest / EELPFC

Optional

Exemption and Exclusion Legend or PFC Code.  Use in conjunction with Revision tag with value of 1 to indicate and trigger new functionality. To activate check boxes use ”30.37a” or “30.37h”.

For example: <EELPFC>30.37a</EELPFC> 

Please refer to the International Mail Manual for further information http://pe.usps.gov/text/imm/immc5_007.htm.

String

whiteSpace=collapse

minLength=0
maxLength=35

eVSPriorityMailIntlRequest / PriceOptions

Optional

Price option for package.

String

Enumerations=

·        RETAIL

·        COMMERCIAL BASE

·        COMMERCIAL PLUS

eVSPriorityMailIntlRequest / Length

Optional

Value must be numeric. Units are inches. If partial dimensions are provided, an error response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non-rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non-rectangular packages.  

 

For more details on dimensional weight pricing or dimension validation reference IMM https://pe.usps.com/text/imm/welcome.htm

Decimal

minExclusive=0.0
totalDigits=10  

eVSPriorityMailIntlRequest / Width

Optional

Value must be numeric. Units are inches. If partial dimensions are provided, an error response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non-rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non-rectangular packages.  

 

For more details on dimensional weight pricing or dimension validation reference IMM https://pe.usps.com/text/imm/welcome.htm

Decimal

minExclusive=0.0
totalDigits=10  

eVSPriorityMailIntlRequest / Height

Optional

Value must be numeric. Units are inches. If partial dimensions are provided, an error response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non-rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non-rectangular packages.  

 

For more details on dimensional weight pricing or dimension validation reference IMM https://pe.usps.com/text/imm/welcome.htm

Decimal

minExclusive=0.0
totalDigits=10  

eVSPriorityMailIntlRequest / Girth

Optional

Value must be numeric. Units are inches. If partial dimensions are provided, an error response will return. Length, Width, Height are required for accurate pricing of a rectangular package when any dimension of the item exceeds 12 inches. In addition, Girth is required only for a non-rectangular package in addition to Length, Width, Height when any dimension of the package exceeds 12 inches. For rectangular packages, the Girth dimension must be left blank as this dimension is to only be used for non-rectangular packages.  

 

For more details on dimensional weight pricing or dimension validation reference IMM https://pe.usps.com/text/imm/welcome.htm

Decimal

minExclusive=0.0
totalDigits=10  

eVSPriorityMailIntlRequest / ExtraServices

Optional

Groups extra services elements

(Group)

 

eVSPriorityMailIntlRequest / ExtraServices / ExtraService

Optional

Parameters used to specify desired ExtraService. Additional occurrences for future. 

Note: The <InsuredAmount> tag is used to indicate insurance.

Extra Service Name

Service

ID

e-USPS Return Receipt

105

For example: <ExtraService>105</ExtraService>

String

whiteSpace=collapse

Enumerations=

·        105

eVSPriorityMailIntlRequest / ActionCode

Optional

Used to specify the action code. Value is included in the Shipping Partner Event file for customers who have chose to have a Shipping Partner Event file submitted to USPS on their behalf.

M0 – Mailer Owner

S0 – Service Provider

For example: <ActionCode>M0</ActionCode>

String

Enumerations=

·        M0

·        S0

eVSPriorityMailIntlRequest / OptOutOfSPE

Optional

Allows a customer to opt out of SPE file creation. “false” WILL create a SPE file. Note: This request tag is case sensitive.

Boolean

Enumerations=

·        true

·        false

eVSPriorityMailIntRequest / 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

eVSPriorityMailIntRequestt / AccountZipCode

Optional

ZIP of Account Post Office where mailed if different from <FromZip5/>. Written to Postal Manifest Detail record. Must be valid ZIP Code.

For example: <AccountZipCode>00962</AccountZipCode>  

String

whiteSpace=collapse

length=5

pattern=\d{5}  

eVSPriorityMailIntRequest / ImportersReferenceType

Optional

Tax code / VAT no. / Importer Code.

String

minOccurs=0

Enumerations=

·        TAXCODE

·        VAT

·        IMPORTERCODE

eVSPriorityMailIntRequest / ImportersTelephoneNumber

Optional

For Importer:  10 digits (including area code), with no punctuation. Use format: 2125551234

For example: <ImportersTelephoneNumber>5555555555</ImportersTelephoneNumber>

String

whiteSpace=collapse

length=10

pattern=\d{10}

eVSPriorityMailIntRequest / ImportersFaxNumber

Optional

For Importer: No format checking is done on international fax numbers.

For example: <ImportersFaxNumber>011 52 (322) 222-0074</ImportersFaxNumber>

String

maxLength=30

eVSPriorityMailIntRequest / ImportersEmail

Optional

For Importer: Complete valid e-mail address is Required if tag is used.

For example: <ImportersEmail>cpapple@email.com</ImportersEmaill>

String

maxLength=30

whiteSpace=collapse

pattern=([\w\-\.]+)@(([\w-]+\.)+)[a-zA-Z]{2,4}

eVSPriorityMailIntRequest / 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. See International Mail Manual (IMM) Section 241 for more information.

For example: <Machinable>false</Machinable> 

Boolean

default=true

whiteSpace=collapse  

eVSPriorityMailIntRequest / DestinationRateIndicator

Required

Required for destination entry packages.

·