postalref

Current Web Service Description Languages (WSDLs)

The current WSDLs are the zip files of Web Services Description Language and XML Schema Definition files that USPS posts for Mail.XML. Software developers build Mail.XML software from them. Each download matches one environment, Mail.XML version and message type.

Updated October 31, 202614 sources

What it is

WSDL, Web Services Description Language, is an XML-based language that describes web services and how to access them. A WSDL describes a network service as a set of endpoints that operate on messages.

Mail.XML is an XML-based specification for web services. Customers use it to send detailed mailing information to PostalOne!. The USPS-provided WSDL and XSD files standardize that data exchange between PostalOne! and customers.

USPS supports WSDLs for these systems:

  • FAST
  • PostalOne!
  • eDoc
  • Full-Service Data Feedback
  • Profile Management

The Mail.XML technical specification gives the WSDL links for every supported Mail.XML version.

How it works

A developer picks the WSDL for the environment the software runs in and the Mail.XML version it exchanges. Every request then passes a USPS check of the user information before PostalOne! processes it.

  1. Download the zip of WSDL and XSD files for the environment and Mail.XML version.
  2. Build the Mail.XML software from the USPS-provided WSDL and XSD files.
  3. Start the software approval process with the PostalOne! Help Desk.
  4. Test the software in TEM until USPS approves it for Production.
  5. Send requests in Production with a valid, active USPS user ID and password.

Environments

USPS posts WSDLs in five categories. Each environment's WSDLs are one zip file, such as 2.4 PROD Rel64.zip for Production.

  • CAT holds the WSDLs for the upcoming release, open only to selected mailers in the USPS CAT certification phase.
  • TEM is the Mail.XML test environment that all new customers must test in, and it simulates Production.
  • Pre-Production holds pre-release software for testing software development with production data.
  • Production is where customers that USPS approved in TEM send their transactions.
  • Push Subscription is for customers who receive data feedback on their own servers automatically, at a set time.

Pull and push

A pull message is a request from the client, answered by a response to the client. With pull, the mailer's software sends a query request, and USPS answers with a query response that holds the data.

A push message sends data to a client that did not request it. A defined trigger can set it off. In a notification, USPS tells the customer's server that a mailing's data is ready, and the customer's software then pulls it. In a delivery, USPS sends the data to the customer's server on the customer's schedule.

A customer can subscribe to push with profile request messages that PushUserProfileInfo.xsd describes, a file that comes with the WSDL. Push sends data to the customer's web service over Secure Socket Layer communication. A mailer testing push needs a signed certificate from a Certification Authority before Production.

Message-type WSDLs

WSDLs come in two types, the message-type WSDL and the string-type WSDL. USPS supports only the message-type WSDL.

A message-type WSDL lets a customer's automated tool set up its environment without registering each service by hand. It needs new WSDLs with every new Mail.XML version, because it is tightly coupled with the specification version.

Hostnames

A USPS certificate update affects these DNS hostnames:

  • fast.uspspostalone.com
  • p1webservices.uspspostalone.com
  • pcpostage.uspspostalone.com
  • prod1.uspspostalone.com
  • prod1a.usps.com
  • prod1a.uspspostalone.com
  • prodp1.usps.com
  • soa.usps.gov
  • soaprod.usps.gov
  • www.uspspostalone.com

Rules

A web services request must include a valid and active USPS user ID and password as defined in the UserAuthenticationInfo.xsd file that is provided as part of the WSDL downloable files.

Every request must carry a valid, active USPS user ID and password, in the form the UserAuthenticationInfo.xsd file in the WSDL download defines.

When programming to create Mail.XML software, developers must use USPS-provided Web Services Description Language (WSDL) and XML schema document and templates (XSD).

Developers must build Mail.XML software with the WSDL and XSD files that USPS provides.

Customers must use message-type URLs to consume these services.

Customers must call the services through message-type URLs.

Mailers must work with the PostalOne! Help Desk to start the approval process for their software, and must be approved in the TEM environment prior to sending data transactions in the Production environment.

Mailers must start software approval with the PostalOne! Help Desk, and must pass TEM before they send data to Production.

Similarly, USPS customers are required to set up their web services pull software to query PostalOne! servers no more than 200 times in a given 24 hour period for their eDoc, FAST, or Full Service data queries.

Pull software must query PostalOne! servers no more than 200 times in 24 hours for eDoc, FAST or Full-Service data.

The Postal Service is requiring that USPS Mail.XML customers update their Mail.XML software to query the USPS PostalOne! FAST systems no more than seven times per hour.

Mail.XML software must query the PostalOne! FAST systems no more than seven times an hour.

User should always use this link to access the correct and updated version of WSDLs in future.

Users should always get WSDLs from the current WSDLs page, which holds the correct and updated versions.

It is recommended for the mailers not to use these WSDLs unless participating in the CAT phase.

Mailers should not use the CAT WSDLs unless they take part in the CAT phase.

What goes wrong

USPS returns an error message to a request with invalid user information. A fault code comes back whenever a message fails in transmission. A request that is invalid against the XSDs gets fault 403.

USPS no longer supports string-type WSDLs. CAT WSDLs can change at any time without notice. WSDLs and XSDs are revised, replaced or made obsolete as the Mail.XML technical specifications develop.

High volume from FAST and Full-Service data distribution users has hurt the performance of the USPS servers that authorize all Mail.XML transactions. Customers must query different transactions at different times: FAST queries at odd times, and eDoc and data distribution queries at even times.

Terms

Web Services Description LanguageWSDL, Web Service Description Languages
WSDL (Web Services Description Language) is an XML-based language for describing Web services and how to access them.
XML Schema DefinitionXSD, XML schema document and templates
the USPS-provided schemata i.e., Web Services Description Language (WSDL) and XML schema document and templates (XSD) used to ensure conformity and standardization of data exchange between the PostalOne! system and customers.
Mail.xml
Mail.XML is an XML-based DTAC specification for web services.
Mail.XML PullMail.XML Pull (Customer Invokes USPS Web Service), Mail.XML pull messages
Web Services Pull model by which acustomer sends a Web Services based Mail.XML Request message invoking USPS Web Services to pull data in XML format through a Mail.XML Web Service method.
Mail.XML PushMail.XML Push (USPS Invokes Customer Web Service), Push messages, Full-Service PostalOne! Push Data, Push Subscription
Web Services Mail.XML Push model by which the USPS invokes a customer’s Web Service method/URL and pushes XML data to the customer Web Service when the data is available or a notification is sent tothe customer by the USPS that customer’s data is available for download.
Test Environment for MailersTEM, Testing Environment for Mailers, TEM (Testing Environment for Mailers)
The Test Environment for mailers (TEM) is a test platform designed to allow mailers to test their ability to submit electronic mailing information such as Full Service (FS) mailings to the Postal Service.
Preproduction Environment
This environment will contain pre-release software and is intended for mailer testing software development testing with production data.
Production EnvironmentPROD, Production
This environment will be used by all customers that have been approved in the TEM environment by the USPS to start sending the transaction/messages.
PostalOne!PostalOne! system
the information management system that provides an electronic linkage between a customer’s mailing information and the Postal Service’s business mail acceptance and induction processes. It produces postage statements and supporting documentation.

Documents

Technical Specifications

Tech Guides

Release Notes

Contacts

The PostalOne! Help Desk answers questions and problems with the PostalOne! system. It is open Monday through Friday, 8:00 a.m. to 5:00 p.m. CST. Its phone is (800) 522-9085, and its email is postalone@email.usps.gov.

USPS support covers Mail.XML business rules, error codes and exception handling. It does not cover software development tools or programming environments.

Sources