Table of Contents

Mail Tracking Status

This endpoint is used to retrieve the current tracking status for one or more mail pieces.

Definition

Route: /mailpieces/statuses
Method: GET
OperationId: MailTrackingStatus

Permissions

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

  • 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
child_client_id string No Filters results to a specific child client.
mail_piece_id array of string Conditional One or more mail piece identifiers to retrieve status for. Required if tracking_number is not provided. Repeat the parameter for multiple values.
tracking_number array of string Conditional One or more carrier tracking numbers to retrieve status for. Required if mail_piece_id is not provided. Repeat the parameter for multiple values.

At least one of mail_piece_id or tracking_number must be provided.

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 Nullable Description
result object No The standard result envelope. See Result.
mail_piece_statuses array of object No The status records that were found. See Mail Piece Status.
mail_pieces_not_found array of string No Identifiers from the request that could not be matched.

Mail Piece Status

Field Type Nullable Description
mail_piece_id string No The unique identifier of the mail piece.
tracking_status string Yes The current tracking status of the mail piece.
tracking_number string Yes The carrier tracking number, when available. 
{
  "result": {
    "is_success": true,
    "errors": [],
    "message": null,
    "sent_on_utc": "2025-01-01T12:00:00Z",
    "trace_id": "...",
    "correlation_id": "..."
  },
  "mail_piece_statuses": [
    {
      "mail_piece_id": "MP-0001",
      "tracking_status": "In Transit",
      "tracking_number": "9400100000000000000000"
    }
  ],
  "mail_pieces_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
Neither mail_piece_id nor tracking_number was provided. At least one of the properties (MailPieceIDs, TrackingNumbers) must be set.
More than 100 mail pieces were requested in a single call. No more than 100 mail pieces can be requested at a time.
The upstream batch limit was exceeded. Exceeded the OSG Mail API batch limit.

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