postalref

USPS Technical Specifications for Mail.dat and Mail.xml

USPS Technical Specifications for Mail.dat and Mail.xml are the USPS documents that say how PostalOne! accepts mailing data in the two industry formats. Technical programmers and managers use them to build software that submits electronic documentation for mailings.

Updated October 28, 202626 sources

What it is

Mail.dat is the mailing industry's standard file format for sending a mailing's details to USPS. DTAC, the Delivery Technology Advocacy Council, maintains the Mail.dat File Specification. DTAC is a member-driven group of mailing and shipping industry leaders.

The USPS Mail.dat Technical Specification adds the rules PostalOne! applies to Mail.dat files. With Mail.dat, mailers no longer fill in qualification reports and postage statements by hand. PostalOne! generates them from the files.

Mail.XML is an XML-based DTAC specification for web services. The USPS implementation of Mail.XML is a complement to Mail.dat. Mailers may keep Mail.dat as their database and use Mail.XML for business-to-business messages. Mail.XML supports Full-Service, Mixed Service and Co-Palletized mailings.

The two formats differ in who counts the pieces. Mail.dat calculates copies and pieces at each price level from the raw data in its files. In Mail.XML, the mailer gives those numbers directly, so there is less round-off error.

How it works

A Mail.dat job reaches PostalOne! through the Mail.dat Client, a USPS program the mailer installs to validate and upload files. The client runs with a user interface for manual upload or unattended in batch mode.

A Mail.dat job, from approved software to acceptance.

  1. USPS approves the mailer's software in the Test Environment for Mailers before production use.
  2. The mailer builds the job's files in the DTAC Mail.dat format.
  3. The Mail.dat Client validates the files at the mailer's site.
  4. After the files pass, the client uploads them to PostalOne!.
  5. PostalOne! generates postage statements and qualification reports from the files.
  6. Acceptance clerks review those reports together with the physical mail.

In batch mode, the client can also download Status Receipt files. These show which stage of PostalOne! processing each Mail.dat file is in.

Mail.XML works as an exchange of messages instead of a set of files. The mailer sends request messages with container, mailpiece and postage information. PostalOne! answers each one with an Accept response when it validated and uploaded. After an Accept, the mailer may go on with the rest of the messages in that mailing group.

Mail.dat files

PostalOne! uses seventeen Mail.dat files. The first three in the list are:

  • The Header file introduces the job and gives the record count for each file type.
  • The Segment file separates parts of a mailing that need different processing.
  • The Mailpiece Unit file describes the physical mailpiece, such as its dimensions.

Every file in a set shares one eight-character name plus a three-character extension. The name joins the User License Code, a four-character code unique to each Mail.dat licensed user, and the File Set ID, a four-character identifier the user chooses.

PostalOne! lets four DTAC files ride in a file set but does not validate, upload or store their records. The unsupported files are:

  • Seed Name Record, SNR
  • Special Fee Barcode Record, SFB
  • IJ / Container Relationship Record, ICR
  • Extra Piece Detail, EPD

Mail.XML messages

Mail.XML messages fall into six sets, each with its own schema module.

  • Transportation Messages
  • Mailing Messages
  • Data Distribution Messages
  • Identification Messages
  • Supply Chain Messages
  • System Messages

Electronic documentation uses two of those modules, mailxml_mm.xsd and mailxml_sc.xsd. USPS publishes its Mail.XML specification in four volumes by subject:

  • Postage Payment & Reporting, for eDoc
  • Appointment Scheduling, for FAST
  • Profiles & Full-Service Feedback, for MID-CRID
  • Data Distribution

USPS recommends eDoc messages of about 25 MB for best performance. At that size, a MailPieceCreateRequest holds roughly 40,000 to 45,000 pieces.

USPS caps Mail.XML software at seven FAST queries an hour. Web services pull software is capped at 200 queries in 24 hours for eDoc, FAST or Full-Service data.

Versions and environments

Release 65.0 deploys on January 3, 2027. Its Mail.dat specification covers Mail.dat versions 25-1 and 26-1, which support the full-service option. On the Mail.XML side, Release 65 adds version 29.2 and lists two older versions for decommissioning.

The environments are:

  • The Preproduction Environment holds pre-release software for testing with production data.
  • The Test Environment for Mailers is part of the software approval process.
  • The Production Environment takes Mail.dat transactions for postage payment from approved customers.

The Preproduction Environment usually opens about one month before the Production and TEM release.

Rules

Mailers must successfully complete testing Mail.dat in the Test Environment for Mailers (TEM), before files can be submitted in the Production Environment.

A mailer must pass Mail.dat testing in the test environment before it submits files in production.

All file versions must use the Mail.dat Client Software described in detail in this section.

Every Mail.dat version must go through the Mail.dat Client to reach PostalOne!.

The Job ID field in the header must be unique within the PostalOne! System for 13 months.

A Job ID in the Header file must not repeat in PostalOne! within 13 months.

Mailers must include the CSM file for all Update and Change jobs.

Every update or change job must carry the Container Summary file, CSM.

Mailers must include the PQT and the PDR for Full-Service or Mixed Service mailings to ensure that Full-Service feedback is provided.

A Full-Service or Mixed Service mailing must include the Package Quantity and Piece Detail files. These files are what Full-Service feedback depends on.

The mailer must then update the data based on the error messages that were provided and resubmit.

After a Mail.XML Reject response, the mailer must fix the data the errors point to and send the message again.

What goes wrong

The Mail.dat Client sorts files into three output folders: validated, failed and rejected. A file goes to the rejected folder before validation for these reasons:

  • It is not listed in the Header file.
  • It is not a standard Mail.dat file.
  • It belongs to a Mail.dat specification PostalOne! does not support.

PostalOne! rejects a whole Mail.dat job in several cases:

  • Two full-service pieces share an Intelligent Mail barcode value, since full-service mail has no duplicate threshold.
  • The same original or update job arrives twice at the same time.
  • An update or change job leaves out the Container Summary file.
  • A change job sends original records whose values differ from those already submitted.
  • A transportation update arrives more than 30 days after the postage statement mailing date.

A mailer cannot cancel Mail.dat files once a postal employee has frozen the job for processing.

A Mail.XML request that fails validation gets a Reject response. The response carries a ReturnCode and a ReturnDescription that describe the errors. A Mail.XML ContainerUpdateRequest is rejected when it arrives more than 30 days after the postage statement mailing date.

Terms

Mail.dat
Mail.dat is an industry-defined database structure consisting of files linked by key fields.
Mail.xml
Mail.XML is an XML-based DTAC specification for web services.
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.
PostalOne! Mail.dat ClientPostalOne! Mail.dat Client Software, PostalOne! Mail.dat Client Application, Mail.dat client
is used to validate and upload Mail.dat files to the PostalOne! System.
File Validator
checks your Mail.dat files to ensure that all required fields are populated and contain the correct character format.
Status Receipt files
The Status Receipt files provide information about which stage of the PostalOne! Process each Mail.dat file is in.
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.
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.
Preproduction Environment
This environment will contain pre-release software and is intended for mailer testing software development testing with production data.
Electronic DocumentationeDoc, Electronic Documentation of Mailing Information, electronic document, electronic mailing documentation
an electronic postage statement that may also contain specific information about a mailing such as barcode information and qualification reports
User License CodeULC
a four-digit alphanumeric code unique to Mail.dat licensed user
Mail.XML request messages
Mail.XML request messages are used to submit mailing information to PostalOne!

Documents

The page also holds guides for setting up Informed Delivery campaigns through Mail.dat and Mail.XML.

Technical Specifications

Tech Guides

User Guides

Contacts

The PostalOne! System Help Desk answers questions and technical problems with PostalOne!. It is open Monday through Friday, on Central time, and takes email or phone contact. Its phone number is (800) 522-9085. Its email address is postalone@email.usps.gov.

Sources