postalref

eDoc: Mail.dat, Mail.XML and postage statements

Mailers describe a mailing to USPS with electronic documentation, or eDoc, an electronic postage statement they send to PostalOne!, the USPS system that records mailing transactions. Small mailers make it in one of two USPS web tools, Postal Wizard or the IMsb Tool. Mailers with presort software send it as Mail.dat files or Mail.XML messages.

Updated November 5, 202664 sources

Questions

What is eDoc for USPS mailings?

eDoc, short for electronic documentation, is an electronic postage statement that may also carry barcode information and qualification reports for a mailing. It replaces the hardcopy statement and reports. USPS requires it for Full-Service and for Seamless Acceptance, which automates the entry and verification of commercial mailings from their eDoc, barcodes and scans.

What is the difference between Mail.dat and Mail.XML?

Mail.dat stores a whole mailing as a database of linked files, uploaded together; Mail.XML sends mailing information to PostalOne! as separate web service messages. In Mail.XML the mailer supplies the copies and pieces at each price level, while Mail.dat calculates them from the raw data in its files. The two work together: a mailer can keep Mail.dat as its database and use Mail.XML between businesses, as the technical specifications describe.

Can I submit a USPS postage statement online without presort software?

Yes: Postal Wizard, a free online tool in the Business Customer Gateway, takes postage statement information typed into web forms and submits it to the PostalOne! Dashboard. It needs a gateway account with an active mailing permit, and separate software must make the Intelligent Mail barcodes. The IMsb Tool, a free online tool for small-volume mailers preparing their own Full-Service mailings, creates the barcodes too.

What does UPD mean on a PostalOne! postage statement?

UPD, USPS Processing Due, means PostalOne! has received a file and the postage statement is available for USPS to process. If the mailing needs verification, USPS starts it from the Dashboard; if not, USPS finalizes the statement. The Mail.dat technical specification lists every postage statement status with the action USPS takes.

Do I have to test in TEM before sending eDoc to production?

Yes: mailers must pass testing in the Test Environment for Mailers before they submit Mail.dat files in production. Mail.dat and Mail.XML users both go through TEM, and USPS streamlines it for users of TEM-certified software. For Mail.XML, mailers using software USPS has pre-approved are not required to test in TEM, though they may.

What does By/For mean in eDoc?

By/For names who prepared a mailing and whom it was prepared for: the mail preparer is the By, and the mail owner is the For. The eDoc for a Full-Service mailing must name both, but a mail owner with fewer than 5,000 pieces need not be named, except in nonprofit mailings. USPS makes Full-Service data available to each party based on these names, as eDoc explains.

What is a Mail.dat Job ID?

A Job ID is the mailer's own name for a Mail.dat job: a unique alphanumeric field of up to 8 characters, kept in the Header file. It must stay unique in PostalOne! for 13 months, and it finds the job's postage statement on the Dashboard. USPS also gives each job a Mailing Group ID, its own tracking number.

Where can I find PostalOne! release notes?

USPS posts PostalOne! release notes on PostalPro, on a Releases page for each month's deployments. The October 2026 page, for one, has notes for PostalOne! release 64.1.1.0 on October 4 and 64.1.2.0 on October 18, 2026. Release notes give PostalOne!'s planned and actual software updates.

How it fits together

A postage statement must go with every business mailing. It reports the mail presented and certifies that the mail meets the standards for the prices claimed. eDoc sends the statement and its supporting documentation, such as qualification reports, to PostalOne! electronically. PostalOne! is the USPS system that records mailing transactions, receives payments and keeps mailing data. For a permit imprint mailing, USPS acceptance staff finalize each statement to debit the postage account for the full amount.

Small mailers enter a statement in one of two web tools, Postal Wizard or the IMsb Tool. Presort software writes Mail.dat files or Mail.XML messages instead. DTAC, a member-driven group of mailing industry leaders, maintains both formats. The technical specifications add what PostalOne! requires of each. Mail.XML software is built from the service descriptions and message schemas USPS posts on its current WSDLs page.

An eDoc can name its parties: the one that submits it, and the mail owner and mail preparer, called By/For. A Full-Service eDoc must name both, though a mail owner with fewer than 5,000 pieces need not be named outside nonprofit mailings. Under Full-Service, USPS makes data available to the mail owner and preparer based on those names.

Software that writes Mail.dat or Mail.XML is approved in the Test Environment for Mailers before it moves to the production environment. Production takes the transactions for postage payment from customers USPS approved in TEM. PostalOne! changes in numbered releases, and each technical specification names the release and format versions it covers.

Postage statements

A postage statement reports the type and volume of mail, the postage method, the processing category and the total weight. It also certifies that the mail meets the standards for the prices claimed. A qualification report lists how a mailing was presorted, by price category and sortation level. Statement data can be sent electronically or on hardcopy USPS forms.

eDoc reaches PostalOne! by these methods:

  • Postal Wizard, a web tool, takes postage statement information the mailer enters by hand into online forms.
  • The IMsb Tool, a web tool for small-volume mailers, builds a Full-Service mailing and submits its statement automatically.
  • Mail.dat, written by presort software, stores complete information about a mailing as a database.
  • Mail.XML, also from presort software, sends messages to PostalOne! through web services.

From Mail.dat files, PostalOne! generates these reports, among others, and shows them to the mailer:

  • Postage statements and qualification reports.
  • Reconciliation reports, which show how much mail was planned and how much was mailed.
  • eInduction reports, which show each container's payment status before it reaches the entry facility. eInduction verifies the payment and preparation of mail containers from their eDoc, barcodes and handheld scans.

Acceptance clerks check those statements and reports against the physical mail. USPS tracks each Mail.dat job, Mail.XML mailing group and Postal Wizard statement by a Mailing Group ID.

Each statement on the Dashboard has a status that shows its stage and the action USPS takes next. Among the statuses are these:

StatusMeaning
UPDA file has been received and a postage statement is available for processing.
PENThe statement is pending finalization.
FINThe statement has been finalized.
FAIThe statement failed verification.
REWA verification issue sent the mailing back to the mailer for correction or rework.
CANThe mailer canceled the statement.
ESTThe postage is an estimate from preliminary data, not an actual postage statement.

A statement charges its postage to the permit holder. A ghost permit is a record USPS sets up in PostalOne! to name another party on the statement, such as a mail owner authorized for Nonprofit USPS Marketing Mail prices.

postage statement

Also called mailing statement

“Documentation provided by a mailer to USPS that reports the type and volume of mail being presented, type of postage method used, processing category of the mail, total weight of the mailing, and other required information and certifies that the mail meets the applicable eligibility standards for the prices and fees claimed. Postage statement data can be submitted electronically or on hardcopy using official USPS forms or approved mailer facsimiles of those forms.”

PostalOne! reports

“The PostalOne! System uses the Mail.dat files to generate postage statements, qualification reports, reconciliation reports, eInduction reports and other reports for customers who have presented mailings to the Postal Service and displays that generated information back to the customers.”

USPS Processing Due

Also called UPD

“A file has been received and a postage statement is available for processing (USPS Processing is Due).”

Finalized

Also called FIN

“The postage statement has been finalized.”

ghost permit

Also called GH, ghost permit type

“a record set up by the Postal Service in the PostalOne! Database to designate parties on the postage statement that are not the permit holder”

Mailing Group ID

“Mailing Group ID is a unique USPS tracking sequence number.”

qualification report

“A detailed listing of presort makeup of a mailing by price category and sortation level that is part of the documentation required for certain mail classes and products.”

Electronic Documentation

Also called eDoc, 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”

Postal Wizard

Also called PW, PSW, Postage Statement Wizard

“a tool that provides a secure way to submit postage statements online”

PostalOne!

Also called 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.”

Mail.dat files

A Mail.dat job is a set of files, each with its own record type, and USPS extracts the postage statement and documentation from them. Every file in a set shares one eight-character name plus a three-character extension. The name joins the User License Code, unique to each licensed user, and a File Set ID the user chooses.

The files a reader meets first describe the mailing from the top down:

  • The Header file introduces the job, holds its Job ID and counts the records in each file.
  • The Segment file separates parts of a mailing that need different processing.
  • The Mailpiece Unit file describes the physical mailpiece, such as its dimensions.
  • The Container Summary file describes each pallet, sack or tray: its level, destination, entry point and contents.
  • The Container Quantity and Package Quantity files give the contents of each container and each package.
  • The Piece Detail file, or the Piece Barcode file in its place, describes each mailpiece for Full-Service.

Large jobs are often split into production units presented for acceptance over several days or weeks. PostalOne! gets the original file first, then an update for each portion.

The PostalOne! Mail.dat Client validates the files at the mailer's site and uploads them. Its File Validator checks that required fields are filled and in the correct character format. In batch mode, the client validates and uploads files without a person, started by the RunBatchUpload script or on a schedule. Batch mode also downloads Status Receipt files, which show each file's stage in PostalOne!.

Header Record

Also called HDR, Header

“The Header file is an introduction to the entire Mail.dat. It identifies who created the file, what version of the mail.dat standard was used (ensuring compatibility with other users), and when the file was created.”

Job ID

“The Job ID is a unique, 8-character maximum, alpha-numeric field in the Mail.dat file that is user-defined and managed.”

Segment Record

Also called SEG, Segment File

“The Segment file is used to identify all of those addresses within presort that are considered as a group.”

Mailpiece Unit

Also called MPU, Mailpiece Unit File, Mail Piece Unit Record

“The Mailpiece Unit file contains the physical description of the whole mailpiece in terms of physical attributes, such as dimensions and ad percentages.”

Container Summary Record

Also called .csm, Container Summary, Container Summary Record File, Container Summary File

“The Container Summary file identifies each container, its level, its destination, the point of entry and the contents in terms of rates, copies, pieces and weight.”

Container Quantity

Also called CQT, Container Quantity Record

“The Container Quantity file supplies quantitative details about the content of each container.”

Package Quantity Record

Also called PQT, Package Quantity

“The Package Quantity file presents a finer level of detail defining the quantity, rate, weight, and package destination for every package in a container.”

Piece Detail Record

Also called PDR, Piece Detail

“The Piece Detail Record provides information for full-service at the mailpiece level for each individual mailpiece.”

Piece Barcode Record

Also called PBC, Piece Barcode

“The Piece Barcode Record provides select information for full-service at the mailpiece level for each individual mailpiece.”

RunBatchUpload

“Executes batch verification and upload for all files in the repository folder. Add file names to process selected files.”

Mail.XML messages and WSDLs

Mail.XML sends a mailing as request messages, which carry container, mailpiece and postage information. PostalOne! answers each request with a response message. An Accept response lets the mailer send the rest of the mailing group's messages. A Reject response carries a return code and a description of the errors. Mail.XML can also update some details of a mailing faster than Mail.dat, within rules USPS sets.

Mail.XML messages fall into six sets, and each set has its own schema module. eDoc uses two of them: mailxml_mm.xsd for mailing messages and mailxml_sc.xsd for supply chain messages. Transportation messages for FAST, the system for appointments at USPS facilities, have a module of their own.

Developers must build Mail.XML software on the WSDL files and XML Schema Definition files, or XSDs, that USPS provides. USPS posts them for each environment and Mail.XML version on the current WSDLs page. A WSDL definition file is an XML-based document that automates the details of communication between applications. With pull, the mailer's software sends a request and gets a response; with push, USPS sends data without a request. Container Status Query Request messages let a mailer check that its containers passed validation before and after induction.

mailxml_mm.xsd

“This module contains all the mailing messages (eDoc) with their attributes, elements, and complex types that are unique to these messages.”

mailxml_sc.xsd

“This module contains all the supply chain messages (Cross-functional container-based and other Mail.dat/mail.XML update functions) with their attributes, elements, and complex types that are unique to these messages.”

mailxml_tm.xsd

“This module contains all the transportation (or FAST) messages with their attributes, elements, and complex types that are unique to these messages.”

Container Status Query Request and Response messages

Also called Container Status Query Request Message

“Status checking allows mailers to view the status of any given container(s) and ensure that the container is validated during the preinduction and post-induction process”

Current Web Service Description Languages

Also called Current Web Service Description Languages (WSDLs), Current Web Service Description Language (WSDLs), WSDL definition file

“an XML-based document that automates the details involved in communication between applications”

Mail.XML request messages

“Mail.XML request messages are used to submit mailing information to PostalOne!”

Web Services Description Language

Also called WSDL, Web Service Description Languages

“WSDL (Web Services Description Language) is an XML-based language for describing Web services and how to access them.”

Mail.XML Pull

Also called Mail.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 Push

Also called Mail.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.”

Mail owner and mail preparer

The mail owner decides what a mailpiece says, benefits from the mailing and pays for its postage, directly or through a mail service provider. A mail service provider acts for one or more mail owners, who pay it for mailing services. When it prepares their mail, it is the mail preparer in a By/For relationship.

The eDoc submitter is the mailer who submitted the electronic documentation for the mailing. A permit or publication number can name a party, and so can its Mailer ID, the field in Intelligent Mail barcodes that identifies a mailer. A party's Customer Registration ID, a USPS number that identifies a business at one location, can name it too.

Must
eDoc submitters of Full Service mailings are required to accurately identify the Mail Owner and Mail Preparer in the eDoc.

Whoever submits the eDoc for a Full-Service mailing must name the mail owner and the mail preparer correctly.

A mail service provider may ask to use a JACKPOT CRID/MID to name mail owners that each have fewer than 5,000 pieces. It must mail 90% of its eligible volume as Full-Service. A JACKPOT CRID/MID can name only mail owners, never the eDoc submitter or the mail preparer.

By/For

Also called BF

“the mail service provider is acting on behalf of the mail owner, creating a By/For relationship: the mail is prepared by the mail service provider, for the mail owner.”

JACKPOT CRID/MID process

“MSPs who prepare mailings that include mail owners with less than 5,000 pieces per owner and are meeting 90% FullService of eligible volume, may request authorization to use a JACKPOT CRID/MID for identification of this volume.”

Mail Owner

Also called MO

“the business entity, organization, or individual who makes business decisions regarding the mailpiece content, directly benefits from the mailing, and ultimately pays for the postage on the mailpiece directly or by way of a Mail Service Provider”

Mail Service Provider

Also called MSP, Mailing Service Providers, Mailing Agent

“a business entity, organization, or individual acting on behalf of one or more Mail Owners by providing mailing services for which the Mail Owners compensate the Mail Service Provider.”

eDoc submitter

“the mailer who submitted the electronic documentation for the mailing”

PostalOne! environments and releases

PostalOne! runs in separate environments, each with its own WSDLs. TEM, preproduction and production each have their own Mail.dat Client download.

  • The Test Environment for Mailers is part of the software approval process before production.
  • The production environment takes transactions for postage payment from customers USPS approved in TEM.
  • The preproduction environment holds pre-release software for testing with production data.
  • The Customer Acceptance Testing environment, or CAT, holds the WSDLs for an upcoming release, open only to mailers USPS selects for its certification phase.

The preproduction environment typically opens one month before a release reaches production and TEM. USPS posts each month's release notes on a PostalPro Releases page, such as October 2026 Releases. Release 65.0 deploys on January 3, 2027, and covers Mail.dat versions 25-1 and 26-1. It adds Mail.XML version 29.2.

USPS also keeps a Known Issues List for PostalOne! and the Enterprise Payment System.

October 2026 Releases

“Release information for October 2026 deployment.”

January 2027 Releases

“Release information for January 2027 deployment.”

Known Issues List

“A list of the PostalOne! System and Enterprise Payment System (EPS) Known Issues”

Test Environment for Mailers

Also called TEM, 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 Environment

Also called PROD, 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.”

What goes wrong

The Mail.dat Client moves each file to a folder for validated, failed or rejected files. It rejects files the Header file does not list and files that are not standard Mail.dat files. A computer can run a client for each environment, and USPS warns to process production jobs in production.

Resending an original job fails once PostalOne! holds its Job ID, so the mailer sends updates instead. To send the original again, the mailer deletes the job. PostalOne! deletes a job only when none of its statements is in a listed status, such as FIN. A clerk may finalize and then reverse the statements to allow it. Container and tray barcodes from a deleted job cannot be reused for 45 days.

Files can fail to transfer because of a permit. The mailer then checks with USPS that the permit, or the ghost permit, is at the same finance number as the permits that pay for the job's statements. A finance number is the six-digit number of a Post Office or facility, and each permit is established under one. In Mail.dat, the finance number's ZIP Code is in the Mailer Postage Account record.

A statement that fails verification shows FAI, and USPS enters on the Dashboard what happened to it, such as rework or additional postage.

A Mail.XML request that fails validation gets a Reject response, and the mailer must fix the data and resend it. A request invalid against the XSD files gets fault 403, which the current WSDLs page lists.

By/For checks log an error when the owner of 5,000 or more pieces goes unnamed, or when the owner is also the preparer. They also log one when the owner named is a mail service provider. A mail service provider that names itself as owner of small volumes gets error 7140, which eDoc explains.

Index: 115 entries

Program (1)

Systems (15)

Files (25)

Identifiers (3)

Documents (64)

Roles (3)

Terms (4)

Sources