Table of Contents

Mail Tracking Event History

This endpoint is used to retrieve the event history for one or more mail pieces.

Definition

Route: /mailpieces/events
Method: GET
OperationId: MailTrackingEventHistory

Permissions

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

  • 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

Query Parameters

Name Type Required Description
mail_piece_id array of string Yes One or more mail piece identifiers to retrieve events for. Repeat the parameter for multiple values.

Responses

Headers

Key Value Type Description
content-type application/json string

Success

Status Description Body
200 All requested mail piece identifiers returned a result. JSON object
207 Some requested mail piece identifiers did not return a result. The unmatched identifiers are listed in not_found. JSON object

A 200 is returned only when every requested mail_piece_id resolves to a result; in that case not_found is empty. When one or more identifiers cannot be matched, the endpoint returns 207 Multi-Status and lists the unmatched identifiers in not_found.

Response Body

Field Type Nullable Description
result object No The standard result envelope. See Result.
mail_piece_history array of object No The event history per mail piece. See Mail Piece History.
not_found array of string No Identifiers from the request that could not be matched.

Mail Piece History

Field Type Nullable Description
child_client_id string No The child client the mail piece belongs to.
mail_piece_id string No The unique identifier of the mail piece.
tracking_number string Yes The carrier tracking number, when available.
imb string Yes The Intelligent Mail Barcode, when available.
impb string Yes The Intelligent Mail Package Barcode, when available.
events array of object No The ordered tracking events. See Mail Piece Event.

Mail Piece Event

Field Type Nullable Description
status string No The status recorded by this event.
status_changed string No The UTC timestamp at which the status changed.
city string Yes The city associated with the event, when available.
state string Yes The state associated with the event, when available.
zip string Yes The ZIP code associated with the event, when available. 
{
  "result": {
    "is_success": true,
    "errors": [],
    "message": null,
    "sent_on_utc": "2025-01-01T12:00:00Z",
    "trace_id": "...",
    "correlation_id": "..."
  },
  "mail_piece_history": [
    {
      "child_client_id": "CC-01",
      "mail_piece_id": "MP-0001",
      "tracking_number": "9400100000000000000000",
      "imb": "...",
      "impb": "...",
      "events": [
        {
          "status": "Accepted",
          "status_changed": "2025-01-01T09:00:00Z",
          "city": "Newark",
          "state": "NJ",
          "zip": "07102"
        }
      ]
    }
  ],
  "not_found": [
    "MP-9999"
  ]
}

Failures

Status Description Body
400 The request was invalid. See Validation Errors. JSON error
401 The request was not authorized. None
403 The request was not allowed. None
500 An unexpected error occurred. JSON error

Validation Errors

A 400 is returned when the request fails validation. Common causes:

Condition Message
mail_piece_id was not provided. The MailPieceIDs field is required.
More than 5 mail piece identifiers were requested at once. Request cannot have more than 5 mail piece IDs.
The upstream batch limit was exceeded. Exceeded the OSG Mail API batch limit.

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