postalref

Informed Delivery API

The Informed Delivery API is a USPS Application Programming Interface that lets outside integrators communicate with the Informed Delivery application. Mailers and shippers use it to manage interactive Informed Delivery campaigns from their own front-end applications.

Updated October 31, 202637 sources

What it is

Informed Delivery is a free, optional feature that lets residential and PO Box consumers preview their mail digitally. A mailer runs an interactive campaign by giving USPS supplemental content: a Ride-along Image, a Target URL and a Representative Image. The Ride-along Image is a clickable color image that sends the user to the Target URL.

The Informed Delivery API gives integrators the campaign management features of Informed Delivery. Its requests and responses are JSON, and it follows the REST model. An integrator can build an in-house front end, customized to its clients' needs, on top of it. The APIs are available through the Apigee Developers Portal.

The technical specification is written for commercial shippers, mailers, marketers and IT staff who prepare interactive campaigns. It covers Mail campaigns only, and a separate Package Campaign specification is to follow. API version 1.0 is the supported version, with support starting December 1, 2025. Release V1.0.3, the MCP Cloud Cutover of October 2026, documents updates to the APIs.

How it works

When mail processing equipment scans a piece, Informed Delivery matches the Mailer ID and serial number in its Intelligent Mail barcode, or the full barcode, to a campaign. It then applies the campaign treatment, the images and Target URL, to the piece for the consumer.

A mailpiece must be automation compatible and scanned on USPS automation equipment to reach an Informed Delivery user. USPS images the address side of every letter and card that runs through automation equipment.

Every API request carries an OAuth 2.0 token from an App in the Customer Onboarding Portal. The App holds the Consumer Key and Secret that request the token. The token comes from https://apis.usps.com/oauth2/v3/token in production and from https://apis-cat.usps.com/oauth2/v3/token in the Customer Acceptance Testing environment, called CAT.

USPS grants access once onboarding is done and testing in CAT is complete.

The integrator does steps 3 to 6 once for CAT and again for production.

  1. Review the support contacts for the API and for Informed Delivery mail campaigns.
  2. Read the Informed Delivery Interactive Campaign Guide before conducting any campaign.
  3. Register in the Customer Onboarding Portal with existing Business Customer Gateway credentials or new ones.
  4. Get Mailer Campaign Portal access in the Business Customer Gateway for each CRID that makes API calls.
  5. Create an API App in the Customer Onboarding Portal to get a Consumer Key and Secret.
  6. Email the App's Consumer Key, never its Secret, to the ID API Support Team, asking for CAT first.
  7. Test in CAT with the support team, then repeat steps 3 to 6 for production.

The requests

The API has five requests, and each one has a matching response. Each request names the submitter's CRID in its path, such as https://apis.usps.com/informed-delivery-campaigns/campaigns/{CRID} for Create Campaign. The endpoint list gives Edit Campaign the host apis-cat-id.usps.com in production as well as in CAT.

RequestMethodWhat it does
Create CampaignPOSTCreates one campaign.
Add BarcodePOSTAdds barcodes to an existing campaign.
Edit CampaignPUTChanges an existing campaign.
Query CampaignGETReturns one campaign or a filtered collection.
Delete CampaignDELETEDeletes or cancels a campaign, depending on its status.

A Create Campaign request holds one campaign. An Edit Campaign request holds only the fields it changes. The one exception is a switch from a Serial-Range campaign to another type, which sends startSerial and endSerial as empty keys.

A query can return one campaign by its USPS Campaign ID, with its images and Target URL. It can also filter a collection across several fields, and every parameter in one query must match. Results come in pages, and the first page is page=0.

Campaign types and shapes

The campaignType field sets the campaign's level: individual barcodes, a whole Mailer ID or a serial range.

campaignTypeCampaign
A01Non-Sequential Barcodes, called NON-SEQ
A02MID Level Mail Campaigns, Mail only
A03Serial-Range Level, Mail only

A Serial-Range campaign names a start and an end serial number. The range covers at least 5 serials. The serial is 9 digits when the Mailer ID is 6 digits, and 6 digits when the Mailer ID is 9.

A NON-SEQ campaign gets its pieces from Add Barcode requests, while it is Submitted or Active. Each request adds 25 barcodes or fewer. Each barcode is a 31-digit Intelligent Mail barcode.

The mailpieceShape field is LT for a letter, CD for a card or FL for a flat. The Representative Image is optional for letters and required for flats.

Campaign content

The Brand Display Name is the text the consumer sees with the campaign. It, the Campaign Code and the Campaign Title each hold at most 40 characters. A Campaign Code is unique for its campaign's Mailer ID.

The Target URL begins with https:// and holds at most 255 characters. By default, Informed Delivery adds the piece's Mailer ID and serial number to the Target URL when a user clicks it. By default, mail campaigns also show options to share them on social media.

Both images are BASE64-encoded JPG files in RGB. Each image is at most 204,800 bytes.

ImageLargest size
Ride-along Image300 pixels wide by 200 high
Representative Image780 pixels wide by 500 high

A campaign starts no more than 59 days in the future. Its end date falls after its start date.

Campaign status

A campaign is Submitted, Active, Complete, Inactive, Draft, Cancelled or Deleted. An Active, Completed or Cancelled campaign can't be edited.

A Delete Campaign request deletes or cancels a campaign, by its status. A Submitted, Draft or Inactive campaign becomes deleted. An Active campaign becomes cancelled.

Each response carries flags that say what the campaign allows next, such as cancel, true only when the campaign is Active.

Campaign reports

Pre-campaign analysis and post-campaign reports for mail are in the Mailer Campaign Portal. Post-campaign data, such as email opens and click-through rates, also reaches Informed Visibility Mail Tracking & Reporting.

Rules

Therefore, a mailpiece must be automation compatible and scanned through USPS automation equipment to be presented to an Informed Delivery user.

A piece must be automation compatible and scanned on USPS automation equipment. Otherwise its campaign never reaches the consumer.

Campaigns must be submitted prior to 12AM CST the day before the campaign is scheduled to begin.

A campaign must be submitted before 12 AM Central Standard Time on the day before it starts. A campaign can't start on the day it is submitted.

All API integrators must be registered users of the COP.

Every integrator must have an account in the Customer Onboarding Portal.

All API integrators must have access to the Informed Delivery Mailer Campaign Portal (MCP) within the BCG for each CRID that will be used for API calls.

An integrator must have Mailer Campaign Portal access in the Business Customer Gateway for every CRID it calls the API with.

All integrators are required to test in CAT before moving to Production.

Every integrator must pass testing in the Customer Acceptance Testing environment before it gets production access.

For any data fields that are not required or will not be populated, do not include the tag.

A request must not include a tag for an optional field it leaves empty. A blank tag makes the request fail.

All NON-SEQ campaign edits must be done through the API.

A NON-SEQ campaign must be edited through the API, because the Mailer Campaign Portal can't edit one.

It is highly recommended that the ID API JSON YAML be used to validate all JSON messages prior to submission to the ID API.

An integrator should validate every JSON message against the API's YAML definition before sending it.

What goes wrong

Informed Delivery returns its own errors and warnings in the JSON response, while Apigee returns client-side errors. Apigee's errors cover malformed JSON, schema errors and failed authorization or authentication.

Apigee's errors carry an HTTP status code, such as 429 for Too Many Requests. A request that includes an optional tag left blank gets an error response.

Informed Delivery's own errors include its business-rule checks, such as these.

ErrorWhat it means
CampaignCode.NotUniquetoMIDAnother campaign for the Mailer ID has this Campaign Code.
CampaignMID.OverlapAnother campaign has the same Mailer ID and overlapping dates.
CampaignMID.SerialOverlapAnother campaign has the same Mailer ID, overlapping serials and overlapping dates.
MIDOnPiece.BlocklistedThe Mailer ID on the piece is no longer valid.
StartDate.TodayThe campaign starts on the day it is submitted.
EndDate.Exceeds45daysThe campaign runs longer than 45 days.
EndDate.Exceeds62DaysThe campaign runs longer than 62 days.
Campaign.NotEditableThe campaign has barcodes and its start date has come.
Barcode.MoreThan25The Add Barcode request has more than 25 barcodes.
Barcode.InOtherCampaignThe barcode belongs to another Active or Submitted campaign.
RepresentativeImage.RequiredA flat campaign has no Representative Image.

An Add Barcode request can partly succeed. A barcode that fails comes back with no piece ID and its own error.

The CAT Mailer Campaign Portal can't be reached from outside the USPS network, so an integrator can't see its test campaigns there. The ID API Support Team helps verify them instead.

An App created before Mailer Campaign Portal access was granted needs its token refreshed in the Customer Onboarding Portal to add that access.

What the sources leave open

The sources don't say which campaigns each campaign-duration error applies to, or whether production edits really go to the CAT host.

Terms

Informed DeliveryID
Informed Delivery®, a free and optional notification service that gives eligible residential consumers the ability to digital preview their letter-sized mail pieces and manage their packages scheduled to arrive soon.
campaign treatment
Campaign treatment is defined as a set of images (Ride-Along Image and Representative Image) and the Target URL that are applied to a mailpiece IMb.
Ride-along Image
The required Ride-along Image is a clickable color image that directs the user to the Target URL.
Representative Image
The Representative Image (available only on mail campaigns) is a color image chosen by the mailer that will be used in place of the scanned grayscale image of the mailpiece.
Business PortalCOP, Business Portal (Formerly Customer Onboarding Portal), Customer Onboarding Portal, USPS Business Portal
The United States Postal Service (USPS)Business Portal (COP) offers business customers a modern, streamlined way to create and manage a USPS business account set-up and onboard core services.
Business Customer GatewayBCG, BCG (Business Customer Gateway)
where shippers can manage their mailing activity
Customer Registration IDCRID, Customer Registration Identification Number, Customer Registration Identifier, Customer Identifier, Customer Reference ID, Customer Registration Identifications
a USPS-generated numeric code of up to 15 digits that uniquely identifies a business at a specific location
Mailer IdentifierMID, Mailer IDs, Mailer Identification, Mailer Identification Number, USPS Mailer ID
MID is a unique 6- or 9-digit number that identifies the mailer or the mailer’s client.
Intelligent Mail BarcodeIMb, 4CB, Intelligent Mail barcode (piece level barcode), 4CB, 4-CB, USPS4CB, USPS 4-State Customer Barcode, 4-state customer barcode
The IMb is a height-modulated barcode that encodes up to 31 digits of mailpiece data into 65 vertical bars using a 4-state symbology.
Informed Delivery Post CampaignIDPC, Informed Delivery Post-Campaign (IDPC) data, Informed Delivery Post-Campaign (IDPC) Detailed Data, Informed Delivery (IDPC), IDPC data
processing, open, and click-through results for Informed Delivery interactive campaigns

Documents

Technical Specifications

Release Notes

Contacts

The ID API Support Team answers questions on integration, onboarding, CAT testing and production support at USPSInformedDeliveryAPI@usps.gov.

The Informed Delivery Program Office answers questions on mail and package campaigns, program requirements, the campaign portals and reporting at USPSInformedDeliveryCampaigns@usps.gov. Its support team also answers at 1-877-329-7206, 7 AM to 5 PM Central time, Monday through Friday.

Sources