Table of Contents

Mail Piece Detail

This endpoint is used to retrieve detailed information for a single mail piece, including its job, mail class, address details, and event history.

Definition

Route: /mailpieces/{mail_piece_id}
Method: GET
OperationId: MailPieceDetail

Permissions

The user must be a member of one of the following groups to retrieve a mail piece:

  • mailpieces:manager
  • mailpieces:viewer

Request

Headers

Name Description Notes
accept The expected format of the response application/json
osg-client-id The unique identifier assigned to your organization Required
client_customer_id The unique identifier assigned to your client
correlation_id The unique identifier for correlation

Parameters

Name Type Description
mail_piece_id string The unique identifier of the mail piece.

Responses

Headers

Key Value Type Description
content-type application/json string

Success

Status Description Body
200 The request was successful. JSON object

Response Body

Field Type Description
result object The standard result envelope. See Result.
mail_piece_detail object The detailed mail piece record. See Mail Piece Detail.

Mail Piece Detail

Field Type Description
mail_piece_id string The unique identifier of the mail piece.
client_id string The client the mail piece belongs to.
job_id string The job the mail piece was produced under.
mail_class string The mail class of the piece.
received_date string The date the mail piece was received into production.
mailed_date string The date the mail piece was mailed, when available.
delivered_date string The date the mail piece was delivered, when available.
imb string The Intelligent Mail Barcode, when available.
imb_status string The status associated with the IMB.
impb string The Intelligent Mail Package Barcode, when available.
impb_status string The status associated with the IMPB.
tracking_number string The carrier tracking number, when available.
tracking_number_status string The status associated with the tracking number.
document_type string The document type of the mail piece.
current_status string The current status of the mail piece.
events array of object The ordered tracking events. See Mail Piece Event.
has_artifact boolean Whether a viewable artifact exists for the piece.
to_address object The recipient address. See Mail Piece Address.
from_address object The sender address. See Mail Piece Address.

Mail Piece Event

Field Type Description
status string The status recorded by this event.
status_changed string The UTC timestamp at which the status changed.
city string The city associated with the event, when available.
state string The state associated with the event, when available.
zip string The ZIP code associated with the event, when available.

Mail Piece Address

Field Type Description
name1 string The primary recipient name.
name2 string The secondary recipient name.
address1 string The first address line.
address2 string The second address line.
city string The city.
state string The state.
zip string The ZIP code. 
{
  "result": {
    "is_success": true,
    "errors": [],
    "message": null,
    "sent_on_utc": "2025-01-01T12:00:00Z",
    "trace_id": "...",
    "correlation_id": "..."
  },
  "mail_piece_detail": {
    "mail_piece_id": "MP-0001",
    "client_id": "123456789",
    "job_id": "JOB-42",
    "mail_class": "First-Class",
    "received_date": "2025-01-01",
    "mailed_date": "2025-01-02",
    "delivered_date": "2025-01-05",
    "imb": "...",
    "imb_status": "Delivered",
    "impb": null,
    "impb_status": null,
    "tracking_number": "9400100000000000000000",
    "tracking_number_status": "Delivered",
    "document_type": "Statement",
    "current_status": "Delivered",
    "events": [
      {
        "status": "Delivered",
        "status_changed": "2025-01-05T14:30:00Z",
        "city": "Trenton",
        "state": "NJ",
        "zip": "08608"
      }
    ],
    "has_artifact": true,
    "to_address": {
      "name1": "Jane Doe",
      "name2": null,
      "address1": "123 Main St",
      "address2": null,
      "city": "Trenton",
      "state": "NJ",
      "zip": "08608"
    },
    "from_address": {
      "name1": "Acme Corp",
      "name2": null,
      "address1": "1 Corporate Way",
      "address2": null,
      "city": "Newark",
      "state": "NJ",
      "zip": "07102"
    }
  }
}

Failures

Status Description Body
401 The request was not authorized. None
403 The request was not allowed. None
404 The mail piece was not found. See Not Found. JSON error
500 An unexpected error occurred. JSON error

Not Found

A 404 is returned when no mail piece matches the supplied mail_piece_id. The message varies by source:

Condition Message
The upstream service reports the identifier does not exist. Mail piece ID does not exist.
No result is returned and no upstream message is available. Mail piece could not be found.

Copyright © 2025 Output Services Group, Inc. All Rights Reserved.